Instant Articles API

Instant Articles support syndication using the Instant Articles API. This API allows you to create, publish, update and delete Instant Articles directly from your content management system. Automated publication in the Instant Articles format on Facebook also occurs in real time.

Introduction to Using the API

Here’s how to set up automated publishing using the Instant Articles API:

1. Create a Facebook App ID

You'll need an existing Facebook app ID, which is used to issue calls to the Instant Articles API. If you don't already have an app ID, create a new one.

2. Distribute New Articles Using the API

Use the Instant Articles API to distribute your articles to the Instant Articles library for your Facebook Page. Using the API, you can create, update and delete Instant Articles directly from your content management system. Detailed guidance on the Instant Articles API endpoints is provided in the Instant Articles API Reference.

The Graph API Explorer can be a useful way to get started with using the Instant Articles API before you begin integrating the API into your publishing system.

3. Verify that Your Articles Are Processed Correctly

Double check your articles to ensure they are error-free and render properly. See the Testing and Debugging section for instructions on how to troubleshoot and eliminate errors.

4. Update Published Articles

At times you may want to update the content of a previously published article, as in the case of a developing news story. To automatically specify an article to update and republish, its HTML must include the op-published and op-modified <time> elements, and the updated article must be redistributed through the API.

5. Ensure Facebook Crawler Can Reach Your Content

To properly distribute your content to Instant Articles, ensure your content is visible to our crawler. If you normally restrict access to your content, you'll need to add our crawler to your allow list. Please refer to our Facebook Crawler guide for advice on how to identify our crawler and preferred approaches to allow listing.

6. Submit Articles for Review

You will be able to begin publishing Instant Articles after a sample of your articles has successfully passed the Article Review process. Until then, you won't be able to publish Instant Articles.

Requirements

Before you begin using the Instant Articles API, you must have:

• An existing Facebook page, which is used to publish Instant Articles. If you don't already have an existing Page, create a new one.
• An existing Facebook app ID, which is used to issue calls to the Instant Articles API. If you don't already have an app ID, create a new one.

Authentication

All Instant Articles requests must be signed with a page access token, by which you can make API requests on behalf of your Facebook page. Page access tokens can only be generated on behalf of a person that has an Admin role on your Facebook page.

The following steps outline the approach for generating a valid page access token which you can use to issue Instant Articles requests.

1. Generate a User Access Token

In order to generate a page access token, you must first create a user access token by authenticating a person with your app and requesting the pages_manage_instant_articles and pages_show_list extended permissions. User access tokens are generated through the Facebook Login dialog, which prompts the person to grant the pages_manage_instant_articles and pages_show_list permissions to your app. You may use Facebook's Javascript SDK to invoke the Login Dialog or manually build the login flow on your own.

Once you have successfully generated a valid user access token, you will need to transfer the token to your servers in order to extend the life of the token and retrieve the page access token.

For more information on how to generate a user access token, refer to our User Token documentation.

2. Exchange for a Long-Lived Token

The user access token generated by the authentication flow will only last for about an hour or two, so you will want to extend the life of the token in order to maintain the ability to issue requests to the Instant Articles API on an ongoing basis. Once you have generated a valid user access token, you can exchange this token for a long-lived user access token, which will provide you with the ability to then retrieve a page access token that does not expire.

From your server, issue the following call in order to exchange the short-lived user access token for a long-lived token:

GET /oauth/access_token?  
    grant_type=fb_exchange_token&           
    client_id={app-id}&
    client_secret={app-secret}&
    fb_exchange_token={short-lived-token} 

You can find the App ID and App Secret for your app on your App Dashboard.

For more information on generating long-lived tokens, refer to our Access Token documentation.

3. Retrieve Page Access Token

Once you have generated a long-lived user access token, you can retrieve a page access token that never expires. Issue the following call, which will return a list of pages that the person has access to and will include the page access token for the page:

GET /{user-id}/accounts

If the person manages multiple pages, you will need to lookup the page token by the ID of the page:

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }, 
}

Retrieve the page access token from the access_token field for the desired page and store this token on your servers in order to issue requests to the Instant Articles API on behalf of this person.

List All Articles

To get the full list of article IDs that have been created for a specific Facebook Page, issue a GET request to:

https://graph.facebook.com/{page-id}/instant_articles

Fields

Example Request

GET https://graph.facebook.com/{page-id}/instant_articles?access_token={access-token}

Example Response

{
  "data": [
    {
      "id": "1234",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    {
      "id": "1235",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    {
      "id": "1236",
      "html_source": "<!doctype html>...",
      "canonical_url": "http://..."
    },
    ...
  },
  "paging": {
    "cursors": {
      "before": "1a2B3c4D5e6F7g8H9i0J",
      "after": "1A2b3C4d5E6f7G8h9I0j"
    },
    "next": "https://graph.facebook.com/{page-id}/instant_articles?access_token=...&amp;pretty=1&amp;limit=25&amp;after=1A2b3C4d5E6f7G8h9I0j"
  }
}

Look Up Article ID

To lookup the article ID of an Instant Article based on its canonical URL, issue a GET request to:

https://graph.facebook.com?id={canonical-url}&fields=instant_article

Fields

Example Request

GET https://graph.facebook.com?id={canonical-url}&fields=instant_article&access_token={access-token}

Example Response

{
  "instant_article": {
    "id": "1234"
  },
  "id": "http://www.mysite.com/myarticle"
}

Get Article Details

To get the details for an individual Instant Article based on its article ID, issue a GET request to:

https://graph.facebook.com/{article-id}

Fields

Example Request

GET https://graph.facebook.com/{article-id}?access_token={access-token}

Example Response

{
  "id": "1234",
  "html_source": "<!doctype html>...",
  "canonical_url": "http://..."
}

Create a New Article

To create a new Instant Article, issue a POST request to:

POST /{page-id}/instant_articles

Fields

Example Request

curl \
    -F 'access_token={access-token}' \
    -F 'html_source=<!doctype html>...' \
    -F 'published=true' \
    -F 'development_mode=false' \
    https://graph.facebook.com/{page-id}/instant_articles

Example Response

{
  "id": {import-status-id}
}

Once article has been posted through this endpoint, Facebook will begin processing the article's markup and importing the media assets contained with the article content asynchronously. This endpoint returns an import status ID, which can be used to determine the when the article has been successfully imported or if any errors occurred during the import process.

The endpoint for monitoring the import status of an article is outlined below in this document.

Update an Existing Article

Updates to existing Instant Articles follow the same approach used to creating a new Instant Article. If the article being posted contains the same canonical URL if an existing Instant Article, the markup of the existing article will be updated with the new markup included in the POST.

Delete an Article

To delete an Instant Article, issue a DELETE request to:

DELETE /{article-id}

Fields

Example Request

DELETE https://graph.facebook.com/{article-id}?access_token={access-token}

Example Response

{
  "success": true
}

Get Article Import Status

To get the latest import status for an Instant Article, issue a GET request to:

https://graph.facebook.com/{import-status-id}

Fields

Example Request

GET https://graph.facebook.com/{import-status-id}?access_token={access-token}

Example Request: Additional Fields

GET https://graph.facebook.com/{import-status-id}?fields=errors,html_source,instant_article,status&access_token={access-token}

Example Response: Success

{
  "id": "1234",
  "status": "SUCCESS"
}

Example Response: Success With Additional Fields

{
  "html_source": "<!doctype html>...",
  "instant_article": {
    "id": "1234",
    "html_source": "<!doctype html>...",
    "canonical_url": "http://..."
  },
  "status": "SUCCESS",
  "id": "5678"
}

Example Response: Errors

{
  "id": "1234",
  "status": "IN_PROGRESS",
  "errors": [
    {
      "level": "ERROR",
      "message": "Could not find the Canonical URL within the document: Specify a valid canonical URL using <link rel=\"canonical\" and href=\"canonical url\">"
    }
  ]
}

Transform an Article

The Instant Articles Transformer API enables you to transform regular HTML articles into Instant Articles markup by setting up a set of rules indicating how to transform the Article. This the standard Facebook Instant Articles SDK PHP available as a service for transformation of HTML into Instant Articles markup.

POST /instant_articles/transformer

Authentication

This endpoint requires a simple App token, which means you just need to have an application and get the token using your key and secret. The following steps outline the approach for generating a valid Application token, so you can perform the requests to transform content.

GET /oauth/access_token
    ?client_id={app-id}
    &client_secret={app-secret}
    &grant_type=client_credentials

You can find the App ID and App Secret for your app on your App Dashboard.

For more information on how to generate a user access token, refer to our Page Access Token

Fields

Example Request

POST https://graph.facebook.com/instant-articles/transformer
    ?access_token={GENERATED_APP_ACCESS_TOKEN}
    &html_url={THE_URL_OF_PAGE_BEING_CONVERTED}
    &rules_url={THE_URL_OF_RULES_TO_CONVERT_HTML_INFORMED}

Example Response

{
  "instant_article_markup": "<!doctype html>
  <html>
  <head>
    <link rel=\"canonical\" href=\"http://example.com/article.html\"/>
    <meta charset=\"utf-8\"/>
    <meta property=\"op:markup_version\" content=\"v1.0\"/>
  </head>
  <body>
    <article>
      <header>
        <h1>Title</h1>
      </header>
      <p>Some paragraph converted</p>
      ...
    </article>
  </body>
</html>",

  "instant_article_warnings": [
    "HERE GOES THE WARNING MESSAGES"
  ],

  "instant_article_logs": [
    "[INFO] Transformer initiated using encode [UTF-8]",
    "[INFO] Transformer finished in 149 ms with (0) warnings"
  ]
}

Response Fields

Troubleshooting

This GraphAPI endpoint

/instant_articles/transformer

is a service using the Facebook Instant Articles SDK PHP open source project under the hood. So knowing how it works is a good place to start.

Also be aware that you can enable DEBUG level information retrieval by sending to parameter log_level the value DEBUG, which will bring way more information about the transformation process and how the rules were processed.

Another good hint is to play around with this endpoint on the Open Graph Explorer tool. Where you can try transform your articles or even try to convert some public articles on internet.