Open Graph Stories

Post rich, structured stories from your app using a strongly typed API.

Open Graph Stories in iOS Publish Open Graph stories from your iOS app.

Open Graph Stories in Android Publish Open Graph stories from your Android app.

Open Graph Stories on Web Publish Open Graph stories from your website or web app.

How It Works

People use stories to share the things they're doing, the people they're doing them with and the places where they happen. Let people share stories about your app on Facebook through a structured, strongly typed API.

To publish Open Graph stories with the Share dialog, you do not need to implement Facebook Login or ask for additional permissions. For more information, see Share Dialog.

If you create a custom sharing UI to publishing Open Graph stories, you need to implement Facebook Login and request the publish_actions permission from people using your app. This also means you need to submit your app for review, see Login Review. Both of these steps help make sure people using your app are aware of the action they are taking by sharing and helps provide a high-quality experience.

Open Graph stories have four basic elements:

  • Actor - The person who posts the story

  • App - Every story includes attribution to the app that created it

  • Action - Activity the actor performs

  • Object - The thing the actor interacts with


When you configure an action you should determine the default privacy level. People using the app can choose to override that default privacy level with any privacy level that's more restricted, but not more open.

Using Actions

Actions are the 'verbs' or the things that people can do in your app and publish as stories. Actions are published, retrieved and modified using the Graph API.

Using Objects

Objects are the 'nouns' or targets for actions in your stories. Objects can be used in two different ways: self-hosted (represented by HTML markup on a web page) or created using the Object API.

Best Practices

See our sharing best practices to create the most engaging sharing experience.


Open Graph Stories support internationalization of actions and objects for use in multiple languages.


Open Graph reference documentation.

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

Stories are composed of actions and objects; Facebook has defined a set of common actions and objects, but you may create your own custom actions and objects.

Custom Open Graph Stories must go through a review process for the publish_actions permission. Reviews are generally done within three business days.