---
title: "Configure Instagram"
description: "Complete BYOK setup for Instagram Login: create the Meta app, register Dravo's callback, enable scopes, pass review and connect an account."
section: "Platforms"
url: https://dravo.dev/docs/platforms/instagram
---
# 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

| Setting | Value |
| --- | --- |
| Dravo platform | `instagram` |
| Meta product | Instagram API with Instagram Login |
| Account type | Instagram Business or Creator |
| Facebook Page required | No, not with this login flow |
| Production callback | `https://api.dravo.dev/v1/oauth/instagram/callback` |
| Client identifier | Instagram App ID |
| Client secret | Instagram App Secret |
| Publish scopes | `instagram_business_basic`, `instagram_business_content_publish`, `instagram_business_manage_comments` |
| Analytics scope | `instagram_business_manage_insights` |
| Current Dravo publishing | Image, Reel, carousel (2 to 10) or Story |

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](https://developers.facebook.com/).
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](https://developers.facebook.com/).
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](https://developers.facebook.com/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:

```text
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:

| Scope | Capability | Why Dravo needs it |
| --- | --- | --- |
| `instagram_business_basic` | Publish + analytics | Resolve the professional account id, username, account type and profile data. |
| `instagram_business_content_publish` | Publish | Create media containers and publish images, Reels, carousels and Stories. |
| `instagram_business_manage_comments` | Publish | Create the optional first comment after publishing. Dravo does not use it for moderation workflows. |
| `instagram_business_manage_insights` | Analytics | Read account and media insights such as reach, views, likes, comments, saves, shares and interactions. |

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:

| Group | Scopes |
| --- | --- |
| Publish | `instagram_business_basic`, `instagram_business_content_publish`, `instagram_business_manage_comments` |
| Analytics | `instagram_business_manage_insights` |

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.

```bash
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:

```bash
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:

```bash
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.

| Content | Current support | Notes |
| --- | --- | --- |
| Single image | Yes | JPEG only; text becomes the caption. |
| Reel | Yes | MP4 or MOV; text becomes the caption. |
| Carousel | Yes | 2 to 10 items, images and videos can be mixed. |
| Story | Yes | One image or video, `platform_options.instagram.story: true`. |
| Text only | No | Instagram platform limitation. |
| Account analytics | Yes | Requires `instagram_business_manage_insights`; returns the official metrics Meta exposes for the connected professional account. |
| Post analytics | Yes | Requires `instagram_business_manage_insights`; available for posts with a usable Instagram media id. |
| First comment | Yes | Requires `instagram_business_manage_comments`; Dravo posts one best-effort comment after publishing. |
| Comment moderation / DMs | No | Dravo does not request messaging permissions or expose a comment moderation workflow. |

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](/docs/concepts/media); the asset
must remain reachable while Instagram fetches and processes it.

### Post options (`platform_options.instagram`)

```json
{
  "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"
    }
  }
}
```

| Option | Applies to | Meaning |
| --- | --- | --- |
| `story` | image/video | Publish as a Story instead of a feed post (one media). |
| `share_to_feed` | Reel | Also show the Reel in the main feed. |
| `cover_url` / `thumb_offset` | Reel | Cover image URL, or frame offset in ms. |
| `audio_name` | Reel | Name of the embedded audio. |
| `location_id` | image/carousel/Reel | Tag a location. |
| `user_tags` | image/carousel | Tag accounts (array, JSON encoded for you). |
| `collaborators` | image/carousel/Reel | Co-authors of the post. |
| `alt_text` | image/carousel | Accessibility alt text (not Reels or Stories). |
| `first_comment` | all | Auto-post a first comment after publishing; requires `instagram_business_manage_comments` and reports a warning if the comment fails. |

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](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/)
- [Get started with Instagram Login](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/get-started/)
- [Business Login for Instagram](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login/)
- [Instagram insights](https://developers.facebook.com/documentation/instagram-platform/insights)
- [Instagram media comments](https://developers.facebook.com/documentation/instagram-platform/instagram-graph-api/reference/ig-media/comments)
- [Instagram content publishing](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/content-publishing/)
- [Meta App Review](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review/)

Next, read [Configure OAuth and connect accounts](/docs/guides/connect-accounts)
for the shared backend flow, then [Posts](/docs/api/posts) for the unified
post payload.