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

# Connect Instagram

> Connect Instagram accounts so customer direct messages become sessions the AI answers. Covers supported message types, replies and connection errors.

Connect one or more Instagram accounts so the direct messages customers send them arrive as sessions in your inbox, where the AI answers them and your team can take over. Use it when customers reach your brand through Instagram DMs.

> [!NOTE]
>
> **[Channels → Instagram](https://platform.open.cx/channels/instagram)** in your OpenCX dashboard. Viewing the page needs the **Channels settings** read permission. Adding or disconnecting an account needs the write permission.

## Connect an account

**1. Start the connection**

Go to **[Channels → Instagram](https://platform.open.cx/channels/instagram)** and click **Add account**. Instagram opens in a new tab and asks you to sign in, even if you are already signed in, so you can pick the right account.

**2. Approve access**

Sign in with the account your customers message and approve the access OpenCX asks for: your basic profile and your messages.

**3. Check the account list**

You return to **Channels → Instagram**. The account appears under **Accounts** with its name, username and account ID.

**4. Send a test message**

Send a direct message to the account from a different Instagram account. It appears in the [inbox](https://platform.open.cx/inbox), and the AI replies when the **Instagram** row is on in [Autopilot settings](https://docs.open.cx/safety/autopilot-settings.md).

Repeat **Add account** for each account you want to connect. Adding an account that is already connected refreshes its access. OpenCX also renews each account's access in the background, so you don't need to reconnect on a schedule.

## What OpenCX receives

OpenCX receives **direct messages** only. Comments on your posts and reels are not received, so they never become sessions.

| The customer sends | What appears in the session |
| - | - |
| Text | The text |
| A photo, video, audio clip or file | The first attachment in the message |
| A story that mentions your account | The note *\[Instagram: the customer tagged you in their story]*, plus the story when it is a photo |
| A reply to your story | Their reply, with a note linking to your story |
| A shared post or reel | A note with the link to the post or reel |
| A disappearing photo or video | Nothing is kept |
| Content Instagram doesn't deliver to businesses, such as a collaboration invite | A note saying the customer sent content Instagram doesn't deliver |

The notes are part of the message text, so the AI reads them and your team sees them in the inbox.

Messages your team sends from the Instagram app are not copied into OpenCX. Reply from the inbox if you want the reply in the session history.

## How sessions work

* Each customer has one open session per connected account. Every message they send to that account joins it until the session is closed. Their next message after that starts a new session.
* The session's contact is created from the customer's Instagram name and username, and is updated when either changes.
* Handoff, assignment and [handoff notifications](https://docs.open.cx/slack/connect-slack.md#get-handoff-notifications) work the same as on your other channels.

## How replies are sent

* **AI replies** go out as plain text. Formatting such as bold text is removed.
* **Team replies** from the inbox send the text plus any images, videos and audio clips you attach. Each attachment arrives as its own message before the text. Other file types, such as PDFs, are not sent.
* With **Assist Mode** on for Instagram, the AI's reply stays in the inbox as a suggestion and nothing is sent until a teammate sends it. See [Let the AI draft instead of reply](https://docs.open.cx/safety/autopilot-settings.md#let-the-ai-draft-instead-of-reply).
* If Instagram is turned on in **Settings → CSAT**, the [satisfaction survey](https://docs.open.cx/resources/csat.md) link is sent as a direct message.

## Disconnect an account

Click **Disconnect** on the account's row and confirm. OpenCX stops receiving the account's messages and removes it from the list. Its sessions stay in the inbox, but replies to them can't be delivered until you connect the account again.

## Troubleshooting

After a failed connection, the Instagram page shows **Connection failed** with an error code.

| Symptom | Likely cause | Fix |
| - | - | - |
| Error code `FAILED_TO_EXCHANGE_CODE` or `FAILED_TO_GET_LONG_LIVED_TOKEN` | Instagram didn't complete the authorization | Click **Add account** and approve access again. |
| Error code `FAILED_TO_SUBSCRIBE_TO_WEBHOOKS` | The account was saved, but message delivery couldn't be turned on | Click **Add account** again with the same account. |
| A customer's comment isn't in the inbox | Comments are not received | Ask the customer to send a direct message. |
| None of the above | — | Contact OpenCX support with the error code and the account username. |

***

## Related Documentation

> [card] [Autopilot Settings](https://docs.open.cx/safety/autopilot-settings.md)
>
> Turn AI replies on or off for Instagram.

> [card] [Facebook Messenger](https://docs.open.cx/messenger/connect-messenger.md)
>
> Connect your Facebook Pages.

> [card] [Human Handoff](https://docs.open.cx/handoff/introduction.md)
>
> When the AI hands sessions to your team.

> [card] [CSAT Surveys](https://docs.open.cx/resources/csat.md)
>
> Ask for a rating when a session closes.


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