# Instagram

Connect an Instagram Professional account using Meta Unified Login.

URL: /docs/providers/instagram

An installation administrator first configures the Meta OAuth application and
Business Login configuration. Connecting an Instagram channel requires an
Instagram Professional account (Business or Creator) managed through a Meta
Business Portfolio. Personal Instagram profiles cannot publish through the Meta
Graph API.

For your own eligible business accounts, Meta's Standard Access and app-role
requirements differ from the Advanced Access required to connect external
businesses. See [Meta setup and review boundaries](/docs/providers/setup-effort/#facebook-and-instagram-your-accounts-or-other-businesses)
before starting an App Review process. Postdot does not require every self-hosted
operator to obtain external-business access.

## Prerequisites [#prerequisites]

Before connecting in Postdot, confirm your Meta asset hierarchy in
[Meta Business Suite](https://business.facebook.com/):

- **Business Portfolio**: A Meta Business account that owns or manages your
  application and Instagram assets.
- **Instagram Professional Account**: The target profile must be converted to a
  **Business** or **Creator** account.

A Facebook Page is not required by Unified Login. The account must be shared
with the application through its business portfolio.

## Configure the application [#configure-the-application]

Operators configure the Meta Developer application and Postdot deployment:

### 1. Create the Meta Developer application [#1-create-the-meta-developer-application]

Create an app in the [Meta for Developers](https://developers.facebook.com/) portal:

1. Select **Manage messaging & content on Instagram** as the use case.
2. Associate the app with your business portfolio.

### 2. Configure Facebook Login for Business (Unified Login) [#2-configure-facebook-login-for-business-unified-login]

Meta requires newly created applications to use Facebook Login for Business with
the Unified Login template:

1. Navigate to **Facebook Login for Business** -> **Configurations**.
2. Create or edit a configuration using the **Instagram API (Unified Login)**
   template.
3. Under **Assets**, select **Instagram accounts** (deselect Ad accounts if not
   needed).
4. Under **Permissions**, include:
    - `instagram_basic`
    - `instagram_content_publish`
    - `instagram_manage_messages`
5. Use the template's **System-user access token**. Check its expiration in
   the configuration preview. Postdot preserves a verified non-expiring token
   without assigning a deadline; expiring Unified tokens require reconnection
   when they expire.
6. Note the generated **Configuration ID** (numeric identifier).

### 3. Register the OAuth callback [#3-register-the-oauth-callback]

Under **Facebook Login for Business** -> **Settings**, add your deployment's
callback to **Valid OAuth Redirect URIs** and save the changes:

```text
https://postdot.example/api/oauth/instagram/callback
```

Replace `postdot.example` with your public Postdot API origin. Use a public HTTPS callback.

### 4. Set Postdot environment and OAuth application [#4-set-postdot-environment-and-oauth-application]

1. Add the configuration ID to your Postdot API environment:
    ```dotenv
    POSTDOT_INSTAGRAM_CONFIG_ID=your_meta_configuration_id
    ```
2. In Postdot's **OAuth applications** in the administration settings,
   register the Instagram application:
    - **Client ID**: Your Meta App ID.
    - **Client secret**: Your Meta App Secret.
    - Set the application to **Active** and mark it as default if desired.

## Connect the channel [#connect-the-channel]

1. Open **Channels** in Studio and select **Instagram**.
2. Click **Connect account**. You will be redirected to the Meta Business Login
   flow.
3. Log in with your Meta credentials, select your Business Portfolio, and choose
   the Instagram Professional account to connect.
4. When returned to Postdot, verify the account username and ID shown on the
   channel card.

## Publishing and media requirements [#publishing-and-media-requirements]

Instagram requires an image file for feed publishing:

- **Format**: exactly one JPEG, up to 8,000,000 bytes.
- **Media accessibility**: Uploaded media must be served over a publicly
  accessible HTTPS URL so Meta's servers can retrieve the media container during
  publishing.
- **Captions**: Standard text captions are delivered with the image.

## If authorization or delivery fails [#if-authorization-or-delivery-fails]

- **App mode and permissions**: When the Meta app is in Development mode, only
  users listed under **App Roles** (Administrators, Developers, or Testers) can
  authorize the application.
- **No Instagram accounts found**: Ensure the account is Professional, belongs
  to the selected business portfolio and was shared with the app during consent.
- **Expired tokens**: If access is revoked or token expiration occurs, reconnect
  the channel from Studio. Retrying a failed send without reconnecting will not
  renew credentials.

If Meta's **API setup with Unified login** screen fails to load, use
**Facebook Login for Business** -> **Templates** to create the Unified Login
configuration, then **Settings** to register the callback. A successful setup
still needs a complete authorization and publication check.

## Privacy and data requests [#privacy-and-data-requests]

Read [Application data and privacy](/docs/application-privacy/) for the information
held by a self-hosted instance and [Delete application data](/docs/delete-application-data/)
for disconnection, content removal and requests to its operator. Operators must
publish their own policy and contact procedure for the instance covered by their
Meta application.