Custom Open Graph stories are deprecated in Graph API 2.8. Graph API 2.7 and lower will support custom Open Graph stories according to the following schedule:

  • Support for creating new objects will end in January 2017.
  • Support for publishing existing objects will end October 2017.

Creating Custom Open Graph Stories

This document details how to create and configure custom actions and custom objects for stories. We encourage you to use our built-in actions and objects if possible.

Otherwise, there are a few basic components to creating custom Open Graph stories:

Set Up Your App Namespace

You need to set a unique namespace for your app before you can create, publish, read and update custom actions and objects. You can do this in the Settings section of your App Dashboard.

You'll need to use this namespace in code for actions and objects.

Creating an Object

This is a guide to creating custom objects. To use a standard object, see our guide to using objects.

If you don't have a web server to host your content on, you can upload objects to Facebook using the Object API.

To create a custom object, click Add Object Type in the Object Types section of your App Dashboard. All object type names and properties need to be in English. You'll then be able to edit the object's properties:

We'll make a best guess about the grammar of sentences that include your object, but you may want to adjust those properties.

  • Object Type Name: This is how your object type is referred to in the tool, but you define how it appears in stories by setting singular and plural versions.

  • Singular and Plural: For the singular form of your object,choose the indefinite article - a or an. You can also change the plural form for your object if it's irregular.

  • Inherits From: All objects inherit a set of standard properties from a generic object type, but by changing the Inherits From setting to Place or Business you can add location based properties:

Name Description


Designates an object as a place, using provided latitude and longitude values. See the GeoPoint type reference for more information.


Designates an object as a business, using provided contact_data and hours values. See the reference for more information.

Object Properties

There are three types of object properties:

Adding Custom Object Properties

Standard properties can't be modified or deleted, but you can add more properties by clicking Add a New Property in the Object Types section of your App Dashboard:

Set a name for your property, its type, whether it can be set with multiple values as an array, and whether objects of this type are required to provide this property. Don't forget to Save Changes.


Using Other Objects as Properties

Object properties can reference other object types as custom properties. For example, a cookbook app could let someone could cook a Recipe that referenced an Author. No actions are ever published against any Author object types, but it will still be linked to stories published through this rich metadata.

To do this, just choose the object from the property type dropdown:

The value of these properties is always the canonical URL of the object being published.

Adding location information to actions when people aren't present

One of the most common use cases for using other objects as properties is to provide location information with an action, but not to indicate that the person taking the action is actually at that location. An example would be someone publishing a story that they want to visit a city.

In these cases, add location info to the object type and use the object as a property of the action.

Publish the action as normal with an object as a reference:

POST /me/wantstovisit?

Creating an Action

This is a guide to creating custom objects. To use a standard object, see our guide to using actions.

All action type names and properties need to be in English.

To create a custom action, click Add Action Type in the Action Types section of your App Dashboard.


After adding an action you can add additional properties to the standard set. Note that standard properties cannot be deleted or modified.

After adding a property, you can edit the property name, choose a property type, whether multiple instances of this property can be supplied with each action, and whether the property is required or optional when publishing the action. Don't forget to Save Changes.

Additional Capabilities

After creating an action type, you can add additional capabilities that your users can publish with, such as tagging friends, adding a message, or uploading a photo with their post.

See our guidelines to using additional capabilities for more info.


There are some additional advanced settings that can be changed for custom action types.


This customizes the exact endpoint used when publishing actions, which by default for custom action types is /me/{app-namespace}:{action-type-name}.

Unique Action

Turn this on if there can only be one instance of the action-object pair - for example, a user might only be able to 'vote' once for each 'entry' object.

Require App Token to Publish

This field specifies that the app secret is required to publish activity. For example, some games want to enforce that actions like score or achieve can only be written from that app's servers and not by anyone with an access token.

Once this is enabled, all action publishing calls to the API must be made with a valid app access token.

Geographic Restrictions

This allows you to specify a list of countries that can or cannot use or see this action type. You can also apply restrictions on an app-level or object-level basis.

Configuring Your Story

To associate actions with objects, click Add Custom Story in the Stories section of the App Dashboard.

Select or add your action and object types and hit Create.


After creating your action type, tenses are automatically conjugated. We recommend that you only edit tenses to include a necessary preposition (ex: vote for, comment on) or change the present tense (ex: from "is tasting" to "tastes")

Just hit Edits Tenses from the Open Graph section of your App Dashboard:


Attachments show how your action will render in News Feed and Timeline. You can configure the story as an item with added captions. Just select a story from the Open Graph section of your App Dashboard and hit Edit Attachments:

Attachments are laid out as an item containing some metadata about the story and an image. The layout contains 4 separate lines of captions that you can customize with text and properties from the actions or objects involved with the story.

App Attribution

You can customize the text used to attribute the story to your app by choosing from a list, or you can disable attribution completely if you wish.

Sentence Variations

You can add complexity to stories by editing variations on the story. In this example, the "one to one" story is edited to include adjectives.

Reading and Publishing Custom Types


Reading and Publishing

To read (HTTP GET) or publish (HTTP POST) a custom action:


Updating and Deleting

To update and delete custom actions, use the same calls as for common actions.



The HTML for custom properties should always be prepended by the app namespace similar to this:

<meta property="{namespace}:{custom-object}" content="{value}"/> 


Read a single custom object by issuing an HTTP GET request to the object instance ID.

Read the objects of an object type that someone has connected to because of a specific action type via the Graph API:

GET /me/{namespace}:{action-type}/{object-type}


Update custom objects in the same way you update common objects.


There are currently no supported formatters for Open Graph object types.