Important updates since this guide was originally written:
-
App Review is now required. Since September 2021, Meta requires your app to pass App Review and be approved for the oEmbed Read permission (now called Meta oEmbed Read for apps created after April 8, 2025). Without this, the oEmbed API calls will fail. See Meta’s App Review submission guidance for tips on getting approved.
-
Instagram oneboxes may not render correctly. As of November 3, 2025, Meta removed the
thumbnail_url,thumbnail_width,thumbnail_height, andauthor_namefields from Instagram oEmbed responses. Discourse’s Instagram onebox code currently depends on these fields (lib/onebox/engine/instagram_onebox.rb), which may result in broken or empty embeds. -
Only post and IGTV URLs are supported. Discourse currently only oneboxes Instagram
/p/(post) and/tv/(IGTV) URLs. Reels (/reel/) URLs are not supported. -
The Facebook Developer Console UI has changed significantly since the screenshots below were taken in December 2020. The general steps remain similar, but the exact screens and options may look different.
If you already have a Facebook App associated with your Discourse site, scroll down to Adding oEmbed to your Facebook App.
If you do not have a Facebook Developer account and Facebook App:
Go to https://developers.facebook.com/. You’ll be prompted to log in to your Facebook account if you aren’t currently logged in. You may be asked to ‘convert’ your Facebook account to a developer account if you haven’t done so previously. You may be asked to verify your account with Facebook by adding a phone number or by completing other steps. You’ll need to just follow the prompts and do what Facebook requires of you.
Once you have a Facebook Developer account, click on ‘My Apps’ from the Facebook Developer homescreen:
…and ‘Create App’:
Select an app type of ‘Something Else’ and ‘Continue’:
Enter an ‘App Display Name’ and an ‘App Contact Email’. Once you’ve read through their Terms and Polices, you can click ‘Create App’:
If you are a robot: nothing to see here. Beep bop boop. 
If you are not a robot: click “I’m not a robot”, follow the prompts, and click ‘Submit’.
Congrats! You have a Facebook App!
Adding oEmbed to your Facebook App:
Scroll to the bottom of the list of Products, find ‘oEmbed’ and click ‘Set Up’:
If you agree with how you’re going to use the oEmbed product, click the checkbox, and then click ‘Confirm’:
The oEmbed product has been added. Click on ‘Settings’:
‘Display Name’ and ‘Contact Email’ should already be filled in. You’ll need to enter URLs for your ‘Privacy Policy’ and ‘Terms of Service’. Select a ‘Category’ from the list of available options. Click ‘Save Changes’ when you’re happy with everything:
Click the toggle at the top of the screen to change from ‘In development’ to ‘Live’ mode:
Click ‘Switch Mode’:
Submit your app for App Review (required since 2021):
Before your app can access the oEmbed API in production, you must submit it for App Review and request the oEmbed Read permission (or Meta oEmbed Read for apps created after April 8, 2025).
- In your app’s dashboard, go to App Review → Permissions and Features.
- Find oEmbed Read (or Meta oEmbed Read) and click Request.
- You may need to first make a successful test API call before the request button becomes active. It can take up to 24 hours after your first API call.
- When submitting, provide a URL on your Discourse site that contains an Instagram embed, and explain that your site uses Discourse forum software to embed Instagram posts using the oEmbed API.
See Meta’s oEmbed documentation for detailed submission guidance.
Generate your App Access Token:
Having done all that, we can actually generate an App Token by following Facebook’s instructions on App Access Tokens. You’ll need the value of the ‘App ID’ field, and the value of the ‘App Secret’ field. To get the App Secret, click ‘Show’. You may be asked to reauthenticate yourself or similar, but you should end up with a long hexadecimal value that you can copy:
As per Facebook’s documentation, you need to send those values to Facebook to generate a token. Are you familiar with using curl? Great! They suggest the following (replacing {your-app-id} and {your-app-secret}) with the values you copied from the screen above.
curl -X GET "https://graph.facebook.com/oauth/access_token?client_id={your-app-id}&client_secret={your-app-secret}&grant_type=client_credentials"
Alternatively, copying just the URL (after replacing those two values) to your browser should also work:
https://graph.facebook.com/oauth/access_token?client_id={your-app-id}&client_secret={your-app-secret}&grant_type=client_credentials
Facebook will respond with a small chunk of JSON, that should look something like this example:
{"access_token":"1234567890654321|c3bd55c09fc5e561552ad7a8717","token_type":"bearer"}
Copy the value of your access_token, excluding the quote marks (i.e., in my example it would be 1234567890654321|c3bd55c09fc5e561552ad7a8717), and go to your Discourse site’s Settings. Find the site setting called facebook_app_access_token in the Onebox settings. Paste the ‘access_token’ value in to this field:
Click the 
…and you’re done!
Pasting a URL such as https://www.instagram.com/p/CIRhYzFM7Lu/ in to a post on your site should result in a lovely onebox, just like this one:
https://www.instagram.com/p/CIRhYzFM7Lu/
Last edited by @JammyDodger 2024-05-26T06:49:11Z
Check document
Perform check on document:
waiting for my second app to be…
), but the primary different is oEmbed must be requested after your app has passed the App Review.
