Configure Instagram

Dravo connects Instagram through the Instagram API with Instagram Login and publishes through graph.instagram.com. This is the current direct Instagram Login flow, not Instagram Basic Display and not the older Facebook Login flow.

Platform configuration verified against Meta's official documentation on June 24, 2026.

Configuration summary

The callback in this table is fixed for every Dravo customer. Do not replace api.dravo.dev with your product domain.

The setup below has eight steps. Complete Steps 1–7 with an app-role test account first. Request production access in Step 8 only after OAuth and a real test publication both work.

Step 1: Prepare the accounts and URLs

This first step is only to avoid starting in the wrong place. You do not need to complete production review, business verification or every legal URL before creating the OAuth app; those items are covered later when they become relevant.

Have these three things ready:

1. A Facebook account that can access Meta for Developers.
2. An Instagram Business or Creator account for the first test connection. Personal Instagram accounts cannot publish through this API.
3. Access to Dravo Dashboard → Connections, or a Dravo API key if you will create the OAuth app through the API.

You will use three places during the setup:

1. Meta for Developers to create the platform app and copy the Instagram App ID and App Secret.
2. Meta Business Suite if Meta asks you to select or verify the Business Portfolio that owns the app.
3. Dravo Connections to copy the callback, save the credentials and test the connection.

Do not follow legacy setup blindly. Instructions that ask for instagram_content_publish, pages_read_engagement, a Page access token, or a mandatory linked Facebook Page describe the Instagram API with Facebook Login. Dravo's platform uses Instagram Login and the instagram_business_* permissions listed above.

Step 2: Create the Meta app and add Instagram Login

This step is completed entirely in Meta. Nothing is stored in Dravo yet.

2.1 Register as a Meta developer

Navigation: developers.facebook.com → Get started. If registration is already complete, the top-right menu shows My Apps instead.

If you do not already have one:

1. Open Meta for Developers.
2. Choose Get started or My Apps and sign in with the Facebook account that should administer the integration.
3. Accept the platform terms and complete developer registration.
4. Complete identity, email, phone or two-factor verification if Meta requests it. Unresolved verification can prevent the app from going live later.

Use an organizational administrator rather than a personal account that may leave the company. Add a second app administrator before production.

2.2 Create a Business app

Navigation: Meta for Developers → My Apps → Create app.

1. Open My Apps and select Create app.
2. On Select a use case, choose the option that mentions accessing the Instagram API. Some dashboard versions place it below Other.
3. If Meta shows Select an app type, choose Business.
4. On App details, enter an app display name and monitored contact email.
5. Under Business Portfolio, select the portfolio that should own the app.
6. Choose Create app, confirm your password if requested, and verify that the new app opens in the App Dashboard.

Keep development and production in separate Meta apps when possible. It avoids invalidating customer consent while testing callbacks or permissions.

2.3 Add Instagram API with Instagram Login

Navigation: App Dashboard → Use cases → Instagram API → Customize. Depending on the dashboard version, the same screen appears as App Dashboard → Instagram → API setup with Instagram login.

Inside the Meta App Dashboard:

1. Find Instagram among the available use cases/products.
2. Choose the setup for Instagram API with Instagram Login.
3. Accept the product terms and open its API setup page.
4. Confirm that the setup shows an Instagram App ID and configuration for Instagram Login/business login.

Do not select Instagram Basic Display. If the only documentation or fields you see revolve around Facebook Pages and Page tokens, you are configuring the Facebook Login variant rather than the platform implemented by Dravo.

2.4 Complete the required app details

Navigation: App Dashboard → App settings → Basic.

Open App settings → Basic and complete the fields Meta requires for a live application:

1. Confirm the app display name and contact email.
2. Add the app domain for your product.
3. Add the Privacy Policy URL.
4. Add the Terms of Service URL when Meta shows the field.
5. Add user data-deletion instructions or a deletion callback.
6. Upload the app icon and select its category.
7. Confirm the Business Portfolio and complete requested verification details.

These fields do not change Dravo's OAuth request, but incomplete compliance metadata commonly blocks App Review or live mode.

Step 3: Register the callback and permissions

The callback and scope list must match Dravo exactly. Changing either after a user connects requires that account to authorize again.

3.1 Add the callback URL

Navigation: App Dashboard → Instagram → API setup with Instagram login → Business login settings → Set up. In some layouts, expand Instagram business login before the Set up button appears.

If you use Dravo Cloud, always register this exact callback:

https://api.dravo.dev/v1/oauth/instagram/callback

You can copy the same value from Dravo Dashboard → Connections → Add OAuth app → Instagram. Dravo also returns it as redirect_uri when you create or list an OAuth app through the API.

This value is the same for every Dravo customer. Do not replace api.dravo.dev with your website, dashboard or API domain.

In Meta's Instagram Login/business-login OAuth settings:

1. Find OAuth redirect URIs or Valid OAuth Redirect URIs.
2. Choose Add URI if Meta does not show an empty field.
3. Paste the complete Dravo callback.
4. Fill Deauthorize callback URL and Data deletion request URL with the corresponding public routes from your own product. They are not the Dravo OAuth callback.
5. Choose Save changes and confirm the redirect URI remains listed after the page reloads.

The match is exact. Do not add a wildcard, query string or fragment, and do not paste your frontend return_url. The platform callback and the route Dravo uses to send the user back to your product are different URLs.

3.2 Enable the scopes used by Dravo

Navigation: App Dashboard → Use cases → Instagram API → Customize → Permissions. If Meta uses the classic layout, open App Review → Permissions and Features and search for each permission.

Enable the scopes that match the Dravo features you will use:

New dashboard connections request both publish and analytics, so production apps should enable all four scopes before onboarding users. API integrations that only need publishing may keep the publish scope set and omit analytics by not passing capabilities=publish,analytics to the OAuth start endpoint.

For each permission:

1. Search for the exact scope name, including the instagram_business_ prefix.
2. Choose Add, Request advanced access, or the equivalent action shown by Meta.
3. Confirm the permission appears in the selected use case.
4. Do not add instagram_content_publish, pages_read_engagement or pages_show_list; those belong to the older Facebook Login configuration.

The scope list is controlled by Dravo. In the dashboard, verify that Instagram shows these two groups:

If you use the API, GET /v1/oauth-apps also returns scope_profiles with the same groups. The older top-level scopes field may still appear for compatibility and represents the default publish-only set.

Step 4: Add a development test account

While the Meta app is in development mode, only accounts associated with app roles can authorize it.

4.1 Add and accept the tester role

Navigation in the current Instagram setup: App Dashboard → Instagram → API setup with Instagram login → Generate access tokens → Add account. If Meta manages the account as an app role instead, use App Dashboard → App roles → Roles → Add people.

1. Open the app's Roles or App roles area.
2. Add the Facebook/Instagram account that will test the integration as a developer or tester, following the role type offered by the Instagram setup.
3. Sign in as that invited account and accept the invitation. Creating an invitation is not enough.
4. Confirm the target Instagram profile is Business or Creator.

If Meta sends an Instagram tester invitation, sign in to that Instagram account and open Settings → Website permissions → Apps and websites → Tester invites to accept it. Menu wording can vary slightly between the web and mobile apps.

Use a dedicated professional test account with harmless content. It will also make the App Review screencast and reviewer instructions easier to reproduce.

Step 5: Copy the credentials into Dravo

5.1 Copy the Instagram credentials from Meta

Primary navigation: App Dashboard → Instagram → API setup with Instagram login → Business login settings. Look for the credential block labelled Instagram App ID and Instagram App Secret. If Meta links the secret to the general app page, follow that link to App settings → Basic and return to the Instagram setup after copying it.

Return to the Instagram product's API setup and copy:

1. Copy Instagram App ID — use this as Dravo's client_id.
2. Next to Instagram App Secret, choose Show. Meta may request your Facebook password or two-factor confirmation.
3. Copy the revealed secret — use it as Dravo's client_secret.
4. Confirm the App ID belongs to the app whose callback and scopes were configured in Steps 2 and 3.

These must belong to the same Instagram Login configuration whose callback and permissions you just configured. Do not use a user access token or Page access token. Copy the secret only into a secure password manager or directly into Dravo; never put it in browser code, source control, screenshots or logs.

5.2 Save them from the dashboard

Navigation: Dravo Dashboard → Connections → OAuth apps → Add OAuth app.

1. Open Dashboard → Connections.
2. Select Add OAuth app.
3. Choose Instagram.
4. Give the app a recognizable name such as Production Instagram App.
5. Paste the Instagram App ID into Instagram App ID.
6. Paste the Instagram App Secret into Instagram App Secret.
7. Recheck the callback and scopes displayed in the setup panel.
8. Save the OAuth app.

5.3 Save them through the API

Endpoint: POST /v1/oauth-apps. This call belongs on your backend; never send the Instagram App Secret from browser code.

curl -X POST https://api.dravo.dev/v1/oauth-apps \
  -H "Authorization: Bearer $DRAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "name": "Production Instagram App",
    "client_id": "INSTAGRAM_APP_ID",
    "client_secret": "INSTAGRAM_APP_SECRET",
    "allowed_return_urls": [
      "https://app.acme.com/settings/connections"
    ]
  }'

Check the response before continuing. Its redirect_uri must match Meta, its scopes array must contain the publish permissions, and scope_profiles should list the analytics permission if you plan to use Dravo analytics. Dravo encrypts the secret and never returns it.

Step 6: Connect an Instagram account

6.1 Connect from the dashboard

Navigation: Dravo Dashboard → Connections → Connected accounts → Connect account.

1. Open Connections and choose Connect account.
2. Select Instagram and the OAuth app saved in Step 5.
3. Choose Connect with OAuth.
4. Sign in to the intended Instagram Business or Creator account.
5. Review and grant the requested publish and analytics permissions.
6. Allow Instagram to return the browser to Dravo.

6.2 Connect from your backend

Endpoint: GET /v1/oauth/instagram/start. Use the OAuth app id returned in Step 5 as oauth_app_id.

Request an authorization URL with the selected OAuth app:

curl --get "https://api.dravo.dev/v1/oauth/instagram/start" \
  -H "Authorization: Bearer $DRAVO_API_KEY" \
  --data-urlencode "oauth_app_id=YOUR_OAUTH_APP_ID" \
  --data-urlencode "capabilities=publish,analytics" \
  --data-urlencode "return_url=https://app.acme.com/settings/connections"

Redirect the user's browser to the returned authorize_url. The return_url must already be in that Dravo OAuth app's allowed_return_urls list. It is not sent to Meta as the OAuth callback.

If you omit capabilities, Dravo requests the default publish scope set only. Use capabilities=publish,analytics whenever the connected account should power the analytics endpoints.

Step 7: Verify OAuth and publish a test post

7.1 Verify the connected account

Dashboard location: Dravo Dashboard → Connections → Connected accounts. Open the account's information panel to inspect token health and permissions. The equivalent API is GET /v1/accounts?platform=instagram.

After the browser returns, query the account instead of trusting only the ?connected=instagram parameter:

curl "https://api.dravo.dev/v1/accounts?platform=instagram" \
  -H "Authorization: Bearer $DRAVO_API_KEY"

Check the response in this order:

1. Confirm connection_type is oauth.
2. Confirm the handle and professional account id belong to the intended account.
3. Confirm oauth_app_id identifies the app configured above.
4. Confirm the publish scopes are present.
5. If analytics should work, confirm instagram_business_manage_insights is also present.
6. Confirm token health is active.

7.2 Publish two test posts

Dashboard location: Dravo Dashboard → Playground. Select only the new Instagram account so a failed test cannot publish to another platform.

1. Publish a small JPEG test to validate image containers and captions.
2. Publish a short MP4 or MOV Reel to validate video processing.
3. Confirm both posts appear on the intended Instagram profile.

OAuth can succeed while content publishing remains blocked by access level, account type or media validation, so a real publish is the final configuration check.

7.3 Confirm token handling

Dashboard location: Connections → Connected accounts → account info. Confirm the account reports an active token rather than expired or requires_reconnect.

Dravo exchanges Instagram's short-lived token for a long-lived token and refreshes eligible tokens. The account must reconnect if the user revokes the app, Meta invalidates the grant, or a newly added permission is required.

Step 8: Request production access

Development-mode testing proves the mechanics only. To connect professional accounts outside your app roles, request the production access level Meta shows for every Dravo scope you will request and complete any prerequisite Business Verification.

8.1 Prepare the review package

Navigation: App Dashboard → App Review → Requests or Use cases → Instagram API → Customize → Permissions → Request advanced access. Meta may direct you to Business Verification before opening the review form.

Prepare these items for each requested permission:

1. Use-case explanation: state that users connect their own Instagram professional account so your Dravo-powered product can publish content they create or schedule and, when analytics is enabled, show official performance metrics for their own account and posts.
2. Reason for basic access: explain how you identify the account and display the connected username/profile.
3. Reason for publishing access: explain how you create and publish an image or Reel selected by the user.
4. Reason for comment access: explain that Dravo can add one optional first comment to the user's newly published media, commonly for hashtags or campaign context.
5. Reason for insights access: explain the analytics screen that displays metrics such as reach, views, likes, comments, saves, shares and profile activity for the connected professional account.
6. Reviewer steps: provide exact URLs, credentials and button labels from sign-in to a successful published post.
7. Screencast: show Connect, Instagram consent, the connected-account screen, content creation, the resulting Instagram post and the analytics view if you request instagram_business_manage_insights.
8. Data handling: explain encrypted token storage, disconnect behavior, privacy policy and data-deletion process.

8.2 Submit and repeat the acceptance test

Navigation: App Dashboard → App Review → Requests → Submit for review. After approval, check App settings → Basic or the app header for the current live/production status.

1. Request instagram_business_basic, instagram_business_content_publish, instagram_business_manage_comments and, if analytics is enabled, instagram_business_manage_insights.
2. Submit the review and respond to any clarification requested by Meta.
3. Apply the required live/production setting after approval.
4. Repeat Step 7 using a professional account that has no app role.

Requesting unused messaging permissions adds review work and makes the consent screen harder to justify.

Supported features

Instagram requires media; it does not accept a text-only feed post.

Behind the unified API, Dravo creates a media container (one per carousel item), waits for Instagram to finish processing it, then calls media_publish. Use a stable public URL or upload/import the media first; the asset must remain reachable while Instagram fetches and processes it.

Post options (platform_options.instagram)

{  "account_ids": ["YOUR_INSTAGRAM_ACCOUNT_ID"],  "text": "Launch day",  "media_urls": ["https://cdn.acme.com/1.jpg", "https://cdn.acme.com/2.jpg"],  "platform_options": {    "instagram": {      "location_id": "111",      "collaborators": ["partnerhandle"],      "alt_text": "Two product shots"    }  }}

Send one image, one Reel, 2 to 10 carousel items, or a single Story media. Images must be JPEG; videos must be MP4 or MOV.

Troubleshooting

"Invalid client credentials"

• Confirm you used the Instagram App ID and Instagram App Secret from the same Instagram Login setup.
• Remove whitespace introduced when copying the secret.
• If the secret was rotated, update the Dravo OAuth app before reconnecting.

"Redirect URI mismatch"

• Copy redirect_uri from the Dravo OAuth app instead of typing it manually.
• Compare scheme, hostname, path, case and trailing slash.
• Register the Dravo OAuth callback, not your frontend return_url.

"App is unavailable" or only app admins can connect

• In development mode, add the account as a tester and accept the invitation.
• For external users, complete the required access review and put the app into the production/live state required by Meta.

Missing instagram_business_content_publish

• Confirm the Instagram use case exposes and enables the permission.
• Check its production access/review status.
• Disconnect and reconnect; an old token cannot acquire a new permission.

Missing instagram_business_manage_comments

• Enable the permission in the Instagram use case if you use first_comment.
• Request the access level Meta requires for production users.
• Disconnect and reconnect; old tokens cannot create the first comment.
• If an old token lacks this permission, reconnect the account before using first_comment.

Missing instagram_business_manage_insights

• Enable the permission in the Instagram use case.
• Request the access level Meta requires for production users.
• Start OAuth with capabilities=publish,analytics or connect from the Dravo dashboard.
• Disconnect and reconnect; existing tokens do not gain newly added scopes.

No professional account id is returned

• Confirm the Instagram account is Business or Creator, not personal.
• Confirm you configured Instagram API with Instagram Login rather than Basic Display or a Facebook Page-token flow.
• A linked Facebook Page is not required for this Dravo platform.

OAuth succeeds but publishing returns 403

• Admin/tester access may be masking incomplete production review.
• Confirm the token contains the publish scopes, plus instagram_business_manage_insights if you are testing analytics, and that the app is live for the user class being tested.
• Reproduce with a non-role professional account after approval.

The media container fails

• Ensure images are JPEG and video is MP4 or MOV.
• Make the URL public without authentication and keep it alive during processing.
• Avoid short-lived signed URLs or redirects that expire before Instagram fetches the media.

Official documentation

• Instagram API with Instagram Login overview
• Get started with Instagram Login
• Business Login for Instagram
• Instagram insights
• Instagram media comments
• Instagram content publishing
• Meta App Review

Next, read Configure OAuth and connect accounts for the shared backend flow, then Posts for the unified post payload.