> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Instagram

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect an Instagram professional account to your agent so people reach it through Instagram direct messages. You link the account to a Facebook Page and a Meta app, enter the account's credentials in Artemis, then register a signed webhook that Meta verifies.

The setup requires:

1. [Instagram and Meta setup](#instagram-and-meta-setup): prepare the account, Page, and app, and collect four values.
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
3. [Webhook configuration in Meta](#webhook-configuration-in-meta): verify the callback and subscribe the account.
4. [Verify the connection](#verify-the-connection) with real messages, actions, and media.

After setup, a direct message to the professional account opens a session in Artemis, and the agent replies in the same Instagram conversation.

**Important considerations**

* **The Instagram Account ID selects the connection**: Artemis reads the account ID from `entry.id` in each signed webhook and matches it to the connection. The linked Page Access Token must message on behalf of that same account.
* **Three IDs look alike**: Artemis routes on the Instagram Account ID. The Facebook Page ID and each customer's sender ID appear nearby and never route.
* **Create the connection before you verify the webhook**: Meta's verification request carries the Verify Token but no account ID, so Artemis finds the connection by the stored token.
* **Development mode limits testing**: Only app roles and Instagram testers reach the agent until you complete review and switch the app to Live.

## Prerequisites

Confirm these before you start.

* An Instagram **Business** or **Creator** account. Personal accounts can't use this integration.
* A Facebook Page linked to that account, where you can perform the messaging and moderate tasks.
* A Meta developer account that can create a business app and reveal its App Secret.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Instagram events

Meta sends every event to one generic URL, so Artemis identifies the connection from the signed payload.

| Piece | Owner | What it does |
| - | - | - |
| **Instagram Account ID** | Meta | Routes inbound events by matching `entry.id`. |
| **Page Access Token** | Meta | Authorizes replies. Artemis sends them to `/{InstagramAccountId}/messages` with the token as a Bearer token. |
| **App Secret** | Meta | Verifies `X-Hub-Signature-256` on every inbound POST, over the exact raw body. |
| **Verify Token** | You | Answers Meta's one-time verification challenge. |
| **Webhook URL** | Artemis | Receives events at `/api/v1/channels/instagram/webhook`, with no identifier suffix. |

Artemis scopes each conversation to the account and the sender together, as an `instagram:{accountId}:{senderId}` session.

***

## Instagram and Meta setup

Do this in Instagram and Meta before you open Artemis. Select **Open Meta for Developers** in the setup guide to jump straight there. Meta covers the same ground in its [Instagram messaging get started guide](https://developers.facebook.com/docs/messenger-platform/instagram/get-started).

**1. Use a professional account**

1. In the Instagram app, open your profile, then the menu, then **Settings and privacy**.
2. Switch the account type to **Business** or **Creator**.

**2. Link the account to a Facebook Page**

1. In the professional account settings, connect the Facebook Page that will issue the Page Access Token.
2. Confirm the link from the Page side too.

**3. Create or select a Meta business app**

1. Open [My Apps](https://developers.facebook.com/apps/) and create an app with the business messaging use case, or open an existing one.
2. Add the Instagram product and configure Instagram messaging for the linked Page and account.

Keep development and production on separate apps and accounts.

**4. Assign access and generate the Page Access Token**

1. Grant the app, testers, and system users the Instagram messaging and Page permissions they need.
2. Complete any permission review your app mode requires.
3. Generate a Page Access Token for the linked Page.

The token needs `instagram_manage_messages`. A token from a short-lived user token lasts about an hour, and one from a long-lived user token doesn't expire.

**5. Find the Instagram Account ID**

Copy the numeric professional account ID from the Instagram messaging area of the App Dashboard. You can also query the linked Page for its connected Instagram account in the Graph API Explorer.

Don't use the `@username`, the Facebook Page ID, the Meta App ID, a recipient PSID, or a profile URL.

**6. Copy the App Secret**

1. Go to **App settings** > **Basic**.
2. Select **Show** beside **App secret**, re-enter your password, and copy the value.

Use the App Secret from the same app that owns the Instagram webhook.

**7. Choose a Verify Token**

Create a long random value that only Artemis and the Meta webhook form know. Use a different value per environment.

***

## Artemis channel configuration

Create the connection before you select **Verify and Save** in Meta. Artemis resolves Meta's challenge from a hash of the saved Verify Token.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Instagram** > **+ New**. The **New Instagram Connection** dialog opens, with the setup guide on the left and the fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see. Name it for the account and environment. Routing ignores it. |
   | **Instagram Account ID** | The App Dashboard or Graph API Explorer | The routing key, matched to `entry.id` in each webhook. |
   | **Page Access Token** | The linked Facebook Page | Authorizes replies to `/{InstagramAccountId}/messages`. |
   | **App Secret** | **App settings** > **Basic** | Validates `X-Hub-Signature-256` over the exact raw POST body. |
   | **Verify Token** | You create it | Your shared challenge secret. It isn't the Page Access Token or the App Secret. |
   | **Environment** | Your published environments | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Meta's identity assertion when it links a person to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | Keep it **Active**. Meta's challenge resolves only for an active connection. |

4. Select **Create**.

5. Copy the **Webhook URL** from the connection's summary panel. Don't add an account ID or any suffix.

***

## Webhook configuration in Meta

Registration has two halves. Meta verifies the URL whether or not you subscribe to anything, so finish both.

1. Confirm the Artemis connection exists and is **Active**.
2. In the same Meta app, open the Instagram webhook configuration and paste the Artemis **Webhook URL** exactly.
3. Enter the same **Verify Token** and select **Verify and Save**. Meta sends `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`, and Artemis returns the challenge only when the token matches an active Instagram connection.
4. Subscribe to `messages` for text, attachments, and quick replies, and `messaging_postbacks` for action callbacks. Save the subscription.
5. Confirm the app and the Page subscription connect the same Instagram account. Artemis rejects a connection mismatch.
6. Make sure any proxy in front of Artemis keeps `X-Hub-Signature-256` and passes the raw body unchanged.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Prepare the account | Business or Creator account, linked to a Page where you hold messaging and moderate tasks. |
| Prepare the app | Instagram product added, permissions granted, and a valid Page Access Token. |
| Create the Artemis connection | Saved as **Active** with the account ID, token, App Secret, and Verify Token. |
| Register the webhook | Meta verifies the callback, with `messages` and `messaging_postbacks` subscribed for the intended account. |
| Send a real message | A direct message reaches the agent and one reply returns. |

***

## Verify the connection

Artemis doesn't synthesize Meta events, so a real Instagram conversation is the only end-to-end proof.

1. While the app is in Development, send from an account with an app or Instagram tester role. A public user proves nothing until review and Live mode are complete.
2. Send a unique text to the professional account. Confirm one signed `messages` event, one session, and no processing of echo events.
3. Confirm the reply reaches the original sender through `/{InstagramAccountId}/messages`, inside the messaging window.
4. Select an authored quick reply and a generic-template action. Confirm each resumes the same `instagram:{accountId}:{senderId}` session.
5. Send image, video, audio, and file attachments. Artemis downloads signed Meta CDN URLs promptly, before they expire, and applies size and attachment policy.

| Input | What to confirm |
| - | - |
| `text` | The agent receives and answers it. |
| `image`, `video`, `audio`, `file` | The download succeeds and the agent processes the file. |
| `quick replies`, `postbacks` | The selection returns to the same session with the right action. |

***

## Instagram behavior and limits

Design agent responses to fit these limits.

| Area | Limit |
| - | - |
| Quick replies | Buttons and selects become quick replies, up to 13 options, with titles truncated to 20 characters. |
| Carousels | Generic templates support up to 10 elements, each with up to 3 buttons. |
| Ignored inputs | Artemis ignores shares, story mentions, like-hearts, reels, stickers, and fallback-only attachments rather than creating blank agent turns. |
| Media downloads | Recognized Meta and Instagram CDN hosts only, a 30-second timeout, and a 100 MB streaming cap. |
| Messaging window | Meta can reject replies outside the Instagram messaging window. Test expected conversation timing and approved use cases before production. |

***

## Security and lifecycle

Meta signs what it sends. Your Verify Token only protects the one-time challenge.

* **Signatures**: Artemis rejects any POST without a valid `X-Hub-Signature-256` before queueing. Preserve the request body, content encoding, header, external scheme, and proxy behavior through ingress.
* **Verify Token**: Use a unique random value per environment, and rotate it in Artemis and Meta together.
* **Page Access Token**: It authorizes outbound messages. Encrypt and redact it, grant least privilege, monitor expiry, rotate it, and keep it out of browser code.
* **Environments**: Use separate Meta apps and accounts, or at least isolated credentials, tokens, subscriptions, and connections, for development and production.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Instagram** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its environment badge, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Instagram** and **Channel Connection**. |
| **Identifier** | The Instagram Account ID this connection routes on. Check it first when messages arrive and no session appears. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The callback URL for Meta, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile in place of the fields below. |
> | **Page Access Token** | Replace it when you generate a new token in Meta. |
> | **App Secret** | Replace it if the Instagram product moves to another Meta app. |
> | **Verify Token** | Changing it breaks the Meta webhook until you enter the same value in Meta. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Instagram Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Meta's identity assertion. |
> | **Instagram Account ID** | Read-only, with a copy control. To serve another account, create a new connection. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select **Show more** for the full list, and select **Show preview** to check it. |
> | **Webhook URL** | The callback URL, with a copy control. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers Instagram messages.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Most failures trace to the token, the App Secret, or the subscription.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Meta can't verify the callback | No active connection, mismatched token, or unreachable endpoint | Create the **Active** connection first, use the same Verify Token in both systems, expose public HTTPS, and keep the generic Instagram webhook path. |
| Inbound requests return `401` | Wrong App Secret or altered request | Use the App Secret from the app that owns the webhook, preserve `X-Hub-Signature-256`, and stop proxies from reserializing JSON. |
| No connection found | The payload's account ID doesn't match | Compare `entry.id` with the saved **Instagram Account ID**. A Page ID or sender ID in that field produces this result. |
| Verified but no messages arrive | Missing subscription or ineligible sender | Subscribe `messages` and `messaging_postbacks`, connect the intended account, inspect Meta deliveries, and confirm the sender holds a role in the current app mode. |
| Inbound works but outbound fails | Token, linkage, or window issue | Check the Page Access Token, account linkage, permissions, token expiry, messaging window, and Graph API reachability. |
| Text works but actions don't | Missing postbacks subscription or oversized payload | Subscribe `messaging_postbacks`, and keep quick-reply and template payloads within the limits. |
| Text works but attachments fail | Media outside policy | Use image, video, audio, or file, confirm the signed URL hasn't expired, the host is a recognized Meta CDN, the download is within 100 MB, and your attachment policy accepts it. |
| Meta rejects replies after a delay | The messaging window closed | Reproduce inside an active conversation, and review Meta's current messaging window and approved use cases. |

***

## Meta reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Instagram Platform overview](https://developers.facebook.com/docs/instagram-platform/overview/) | Account eligibility and rate limits. |
| [Instagram messaging get started](https://developers.facebook.com/docs/messenger-platform/instagram/get-started) | App setup, permissions, and Page tokens. |
| [Send a message](https://developers.facebook.com/docs/messenger-platform/instagram/features/send-message) | Outbound formats and messaging window rules. |
| [My Apps](https://developers.facebook.com/apps/) | Returning to an app or checking which app owns a subscription. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Messenger](https://koreai.mintlify.site/agent-platform/channels/messenger)
* [Set up WhatsApp](https://koreai.mintlify.site/agent-platform/channels/whatsapp)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.