Facebook oEmbed

Facebook oEmbed endpoints allow you to get embed HTML and basic metadata for pages, posts, and videos in order to display them in another website or app.

Common Uses

• Rendering Facebook pages, posts, and videos in messaging apps.
• Embedding Facebook pages, posts, and videos in websites and blogs.
• Rendering Facebook pages, posts, and videos in a content management system.

Endpoints

Requirements

• a Facebook developer account
• a Facebook app in Live mode
• an access token
• App Review for the oEmbed Read feature

Limitations

Facebook oEmbed endpoints are only meant to be used for embedding Facebook content in websites and apps. They are not to be used for any other purpose. Using metadata and page, post, or video content (or their derivations) from the endpoints for any purpose other than providing a front-end view of the page, post, or video is strictly prohibited. This prohibition encompasses consuming, manipulating, extracting, or persisting the metadata and content, including but not limited to deriving information about pages, posts, and videos from the metadata for analytics purposes.

App Review

In order to use oEmbed your app must undergo App Review for the oEmbed Read feature.

For the provide a URL where we can test Oembed Read form field, use the oEmbed Endpoints to get the embed HTML for any public post or video on our official Facebook page or Instagram page (or get the embed HTML for either of the pages themselves). Add the returned embed HTML to your own page where you will be displaying oEmbed content and enter that page's URL in the form field.

Once you have been approved for the oEmbed Read feature you may embed your own pages, posts, or videos using their respective URLs.

Access Tokens

The Facebook oEmbed endpoints require either an App Access Token (recommended) or Client Access Token.

App Access Tokens

If your app relies on a backend server, we recommend that you use an App Access Token when accessing the oEmbed endpoint. Rate limits are dependent on the type of token included in the request, and App Token Rate Limits allow for up to 5 million requests per day.

Instructions for generating App Access Tokens can be found in the App Tokens section of our Access Tokens documentation.

Please note that App Access Tokens should never be used client-side. They should always be kept secure and stored on your server. If your app must use a token client-side, use a Client Access Token instead.

Client Access Tokens

If your app must access the oEmbed endpoint from a user agent such as a mobile device or web browser, your app must use a Client Access Token and will be subject to Client Token Rate Limits.

To get a Client Access Token, sign into your App Dashboard and navigate to Settings > Advanced > Security > Client Token.

Unlike App Access Tokens, Client Access Tokens cannot be used in oEmbed endpoint requests on their own, they must be combined with your App ID. To do this, append your token to the end of your App ID, separated by a pipe symbol (|):

{app-id}|{client-token}

For example:

access_token=1234|5678

Rate Limits

Rate limits are dependent on the type of Access Token your app includes in each request.

App Token Rate Limits

Apps that rely on App Access Tokens can make up to 5 million requests per 24 hours.

Client Token Rate Limits

Client Token Rate Limits are significantly lower than App Token Rate Limits. We do not reveal the actual limit as it will change depending on your app activity. However, you can safely assume that your app will not reach its limit unless it exhibits bot-like behavior, such as batching thousands of requests, or sending thousands of requests per agent or app user.

Getting Embed HTML

To get a page, post, or video’s embed HTML, send a request to the corresponding page, post, or video oEmbed endpoint:

Replace {url} with the URL of the page, post, or video you want to query and {access-token} with your App or Client Access Token (or pass it to us in an HTTP header). If you are using a Client Access Token, remember that you must combine it with your App ID using a pipe symbol otherwise the request will fail.

Upon success, the API will respond with a JSON object containing the page, post, or video’s embed HTML and additional data about the page, post, or video. The embed HTML will be assigned to the html property.

Refer to each endpoint’s reference for a list of query string parameters you can include to augment the request. You may also include the fields query string parameter in any request to specify which Fields you want returned. If omitted, all default Fields will be included in the response.

• Oembed Page reference
• Oembed Post reference
• Oembed Video reference

Sample Page Request

curl -i -X GET \
 "https://graph.facebook.com/v21.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

Sample Response

Some values truncated with an ellipsis (...) for readability.

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

URL Formats

The url query string parameter accepts the following URL formats:

Pages

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

Posts

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

Videos

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK JS

By default, the embed HTML contains a reference to the sdk.js JavaScript library. To get embed HTML without the reference so you can load it separately, include the omitscript=true query string parameter.

Passing Access Tokens in a Header

If you don’t want to include your Access Token in your request’s query string, you can pass it to us through an Authorization HTTP header instead.

Authorization: Bearer {access-token}

For example:

curl -i -X GET \
  "https://graph.facebook.com/v21.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."