Facebook Open Graph custom actions tutorial

By: José Padilla

Facebook has extended their Open Graph to include actions and objects created by third party apps enabling these apps to be integrated even deeper into the Facebook experience. I just recently had to implement publishing of custom actions on a project. Facebook’s documentation didn’t help me much at all so I’ll share the minimum requirements you’ll need to do to make this work.

Define Actions

Actions are the interactions that users can perform in your app. Once you’ve created and setup the basic settings for your app you need to head to the Open Graph settings. You’ll first need to define the action. Facebook has a couple of built-in actions: like, publish, read, follow, and watch.

These built-in actions are designed to work with specific built-in objects.

Actions -> Objects

  • LIke -> Any object
  • Listen -> Song
  • Read -> Article
  • Watch -> Video, Movie, TV Show, TV Episode

Also, these built-in actions are shown in a variety of places within Facebook, so the review process will be more detailed as they have to meet specific additional requirements. You can read more about built-in actions.

Define Objects

Objects represent entities that user can act on in your app. As well has with actions, Facebook has built-in objects: link, game, game match, game achievement, profile, book, place, article, movie, and object. You can read more about built-in objects.

Define Aggregations (optional)

Aggregations are summary stories on a user’s Timeline that are defined by your application. Aggregations and reports will give users a cool way to visualize their activity on your app in a cool way. We’ll go into this later.

Publish Actions

Now to the fun part. After you’ve got your action types and object types defined you can start creating and publishing your objects. Open graph objects are just web pages with Open Graph meta tags which are prefixed with “og:”, followed by the specific property to be set. These meta tags specify the object type, name, and other information that describe your object. Each Open Graph object must have its own URL as well.

When a user takes an action in your app, for example read an article, your app will have to do an HTTP POST to the Graph API endpoint:

Facebook will then crawl your web page, read the meta tags, connect the user to the object via the action and publishing it in the user’s Timeline and Ticker.

Note that action types have to be submitted for review before being available to all users, otherwise it will only be available to admins and developers of the app.

How to define a custom action and object

  1. Head to the Open Graph Getting Started page
  2. Define an action and object for your app
  3. You will then be able to define properties for your action. You will also be able to customize the story text and attachment.
  4. After editing your action type, you will be able to customize your object type. You can define custom properties which you will use as Open Graph meta tags later on your web page.
  5. Once your action and object types are defined you will be able to customize the Timeline Aggregations. You can define how your summary will be displayed in a user’s Timeline.
  6. Save and Finish. You will be redirected to your Open Graph Dashboard where you will see all your action and object types and aggregations.

How to publish actions

  1. On your Open Graph Dashboard, click Get Code beside the object you want. This will generate the minimum required Open Graph meta tags you’ll need to add to your web page for that object.
  2. If you are using the Javascript SDK to authenticate your user make sure to add the `publish_actions` permission/scope.
    FB.login(function (response) {
    if (response.authResponse) {
    console.log('Welcome! Fetching your information.... ');
    FB.api('/me', function (response) {
    console.log('Good to see you, ' + + '.');
    } else {
    console.log('User cancelled login or did not fully authorize.');
    }, {
    scope: 'publish_actions'
  3. If you are using the Javascript SDK you can publish an action by invoking an API call.
    FB.api('/me/oghowto:like', //oghowto is the app namespace, like is the action
    'post', {
    demo: ''#demo is the object
    },function (response) {
    if (!response || response.error) {
    alert('Error occured');
    } else {
    alert('Demo was liked successfully! Action ID: ' +;

Here’s a link to the complete web page with minimum requirements, from meta tags to javascript to publish an action:

Implementing Facebook’s Open Graph into your application is not that straightforward, but it is definitely a key aspect for a tight integration with Facebook. Using Facebook’s built-in actions have more requirements so make sure your application meets all of them before submitting your actions for reviewal. Do you already have Open Graph actions submitted to Facebook?