> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/instagram.md).

# Connect a Conversation Platform: Instagram

Connect an Agent to direct messages for an Instagram professional account, including prerequisites, authorization, and FAQs

Instagram direct message integration relies on a Facebook Page. MaiAgent obtains authorization through the Page linked to your Instagram account, then uses that Page to receive and reply to Instagram direct messages. Authorization follows the same process as [FB Messenger](/maiagent-user-guide/en/build/choose-channel/fb.md), except that the Page must first be linked to an Instagram professional account.

## <mark style="color:blue;">Before You Connect</mark> <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

**MaiAgent preparation**

* Create an AI Assistant on the [MaiAgent platform](https://admin.maiagent.ai/)

**Instagram account preparation**

* Switch your Instagram account to a **professional account** (business or creator). Personal accounts cannot be connected
* Link the Instagram account to a Facebook Page (in the Instagram app under <mark style="color:blue;">Settings → Business tools and controls → Linked accounts</mark>, or in the Page's <mark style="color:blue;">Settings → Linked accounts</mark>)
* Allow the Instagram account to receive messages (<mark style="color:blue;">Settings → Messages and story replies → Message controls → Allow access to messages by connected tools</mark>)

**Facebook permission preparation**

* The Facebook account you use to sign in must have been invited to or created a business portfolio and have full control
* If the Page is already in a business portfolio, no additional changes are needed
* If the Page is not in a business portfolio, you must be a Page administrator with full control

{% hint style="info" %}
**Do not have a business portfolio yet?** Follow Meta's official instructions to [create a business portfolio](https://www.facebook.com/business/help/1710077379203657). Its creator automatically has full control.

**How do I check whether I have full control?** In [Meta Business Suite](https://business.facebook.com/), go to <mark style="color:blue;">Settings → Users → People</mark> and click your name to view your permissions. If you only have partial access, ask someone in the portfolio with full control to update your permissions. See [Meta's official permission guide](https://www.facebook.com/business/help/442345745885606).

**Must I add the Page to a business portfolio first?** No. You can claim the Page during authorization. To organize it in advance, follow [Meta's official instructions](https://www.facebook.com/business/help/720478807965744) to add the Page to your portfolio.

**Must I add the Instagram account to a business portfolio?** No. MaiAgent accesses the linked Instagram account through the Page. The Instagram professional account only needs to be linked to that Page.
{% endhint %}

{% hint style="warning" %}
**Already using another support system for Instagram?** After connecting, change the Instagram account's default app under Conversation routing in Meta Business Suite to MaiAgent. Otherwise, the original app will continue handling direct messages. See [Configure Conversation Routing](#conversation-routing). For the full migration process, see [Migrate from Another Support System to MaiAgent](/maiagent-user-guide/en/build/choose-channel/migrate-from-other-platform.md).
{% endhint %}

{% hint style="warning" %}
An Instagram account can only be connected to one channel. To connect it to another Agent, delete the original channel first, then connect it again.
{% endhint %}

## <mark style="color:blue;">Connect Your Account</mark> <a href="#start-integration" id="start-integration"></a>

### 1. Open the Channel Connection Page <a href="#step-go-to-channel-page" id="step-go-to-channel-page"></a>

Click <mark style="color:blue;">Channels</mark> in the left menu, click <mark style="color:blue;">Connect Channel</mark> in the upper right, and select <mark style="color:blue;">Instagram</mark> on the platform selection page.

### 2. Sign In to Facebook and Authorize Access <a href="#step-facebook-login" id="step-facebook-login"></a>

Click <mark style="color:blue;">Facebook Login</mark> and sign in with the Facebook account that manages the Page. The authorization window asks you to:

1. Select the business portfolio to authorize
2. Select (claim) the Page linked to the Instagram account
3. Confirm authorization

MaiAgent only accesses messages for the Pages you authorize and their linked Instagram accounts. It does not access your personal messages.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-dc446ea48022138a20907b9d1282def9e546042a%2Fimage%20(5)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption><p>Facebook Login</p></figcaption></figure>

{% hint style="warning" %}
Allow pop-ups in your browser so the Facebook login window is not blocked. If the Page list does not update after authorization, click <mark style="color:blue;">Reload</mark> in the upper right of the <mark style="color:blue;">Instagram Channel</mark> section to authorize again.
{% endhint %}

### 3. Basic Settings <a href="#step-basic-settings" id="step-basic-settings"></a>

| Field                     | Description                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Channel Name**          | Give this connection a recognizable name                                                                                                               |
| **AI Assistant**          | Select the Agent that will reply to Instagram direct messages                                                                                          |
| **Select Page**           | Select the Page linked to your Instagram account. The system automatically retrieves the Instagram account linked to that Page                         |
| **Enable Reset Commands** | (Optional) Enable this to configure one or more commands, such as “Start over,” that start a new conversation when users send them in a direct message |

{% hint style="info" %}
The list shows all Pages you authorized. If the selected Page is not linked to an Instagram account, saving displays “This Page is not linked to an Instagram account.” Complete the link in Instagram or Page settings, then try again.
{% endhint %}

### 4. Save and Verify the Connection <a href="#step-verify-integration" id="step-verify-integration"></a>

Click <mark style="color:blue;">Connect Channel</mark> to finish creating the connection. Once connected, MaiAgent automatically subscribes to the Page's message events through Meta. No separate Webhook configuration is needed.

Send a test direct message to the professional account from another Instagram account. If the Agent replies normally, the connection is working. You can also open this connection from the MaiAgent channel list and see incoming direct messages under <mark style="color:blue;">All Conversations</mark>.

{% hint style="info" %}
After connecting, click Edit in the channel list to configure additional options, including OCR, answers using system time or the sender's name, human handoff, conversation tags, and access control. See [Channel Settings Overview](/maiagent-user-guide/en/build/conversation-settings/platform-settings.md).
{% endhint %}

## <mark style="color:blue;">Already Using Another Instagram Support System: Configure Conversation Routing</mark> <a href="#conversation-routing" id="conversation-routing"></a>

If your Instagram account has already been connected to another support or marketing app (such as Omnichat or Messenger by SHOPLINE), Meta sends direct messages to the **default routing app** configured in Conversation routing. If MaiAgent is not the default app, the connection may show as successful, but the original app still handles direct messages. MaiAgent does not receive them, and the Agent does not reply.

After connecting, ask an administrator with full control of the Page to change the default app to MaiAgent in [Meta Business Suite](https://business.facebook.com/):

1. Click <mark style="color:blue;">Settings</mark> → <mark style="color:blue;">Integrations</mark> → <mark style="color:blue;">Conversation routing</mark>
2. Select this Instagram account and click <mark style="color:blue;">Settings</mark>
3. Set <mark style="color:blue;">Default routing app</mark> to <mark style="color:blue;">MaiAgent</mark> and click <mark style="color:blue;">Continue</mark>

Keep the following in mind:

* **Configure Messenger and Instagram separately**: Changing only the Page (Messenger) setting leaves Instagram direct messages going to the original app, and vice versa. For Messenger, see [FB Messenger: Configure Conversation Routing](/maiagent-user-guide/en/build/choose-channel/fb.md#conversation-routing).
* **You do not need to remove the original app**: The default app determines who handles conversations that no other app is currently handling. Keeping the original app does not prevent new conversations from reaching MaiAgent.
* **New conversations switch immediately; ongoing ones may not**: After the change, direct messages from new customers or customers who have not interacted for a while go to MaiAgent. However, conversations already active in the original app remain under its control, so follow-up messages continue reaching that system. They switch to MaiAgent only after the original app releases the conversation or the customer sends no messages for about 24 hours (the original app may extend this to as long as 7 days). Earlier messages and conversation history remain in the original system and are not transferred.
* **Ads and dedicated links may specify another app**: If the original app designated a handling app for ads or links leading to Instagram direct messages, conversations from those entry points may still go to the original app regardless of the default. Change these settings to MaiAgent in the original app or ad settings, or disable those entry points first.
* **Verify each route after switching**: Test a new conversation with an account that has never sent a direct message before. Continue checking the original system for a few days around the switch to ensure follow-up messages in ongoing conversations are handled. If you have active ads or links, send a message through each entry point and confirm it reaches MaiAgent. To move ongoing conversations immediately, ask your original system provider to release or hand over those conversations.
* **Revert**: Change the default routing app back to the original app. Reverting also takes immediate effect only for new conversations and those inactive for a while. Follow-up messages in conversations already active in MaiAgent continue reaching MaiAgent until about 24 hours without interaction have passed. Support agents should keep replying in MaiAgent during that time. You can retain the MaiAgent channel for now.

For example, a clothing brand migrates both Messenger and Instagram to MaiAgent but only changes conversation routing for the Page. Messenger test messages reach MaiAgent, but Instagram test direct messages do not. After returning to <mark style="color:blue;">Conversation routing</mark>, selecting the Instagram account, and setting its default routing app to MaiAgent as well, Instagram direct messages start arriving.

{% hint style="info" %}
The English interface calls this setting Conversation routing. The reminder on the MaiAgent channel settings page refers to the same setting as conversation routing. Menu locations may change as Meta updates its interface; see Meta's official [Conversation Routing for Instagram](https://developers.facebook.com/docs/messenger-platform/instagram/features/conversation-routing) documentation for how it works. Before changing it, record the original default app (including if none was set), so you can revert later.
{% endhint %}

## <mark style="color:blue;">Supported Message Types</mark> <a href="#supported-message-types" id="supported-message-types"></a>

| Direction    | Supported Content                                                      |
| ------------ | ---------------------------------------------------------------------- |
| User → Agent | Text, images, videos, voice messages, and stickers; images can use OCR |
| Agent → User | Text and images                                                        |

* **Automatic Markdown-to-plain-text conversion**: Instagram does not render Markdown. Headings, bold and italic text, links, tables, and other Markdown in Agent replies are automatically converted to plain text before sending (links become “text URL”). Text entered by human support agents is unaffected. See [Message Rendering Optimization: Messaging Channels](/maiagent-user-guide/en/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)
* **Consecutive messages are combined into one turn**: When users send several images in succession, or an image followed by text, the Agent waits for the messages to arrive before replying once. For image-only messages, it waits about 4 seconds after the last message with no new messages, up to about 20 seconds; receiving text triggers an immediate reply. Only one turn per conversation is processed at a time
* **24-hour reply window**: Meta only allows replies within 24 hours of the user's last message. Messages sent after that window are marked [Not Delivered](/maiagent-user-guide/en/serve/daily-operations/reply.md#delivery-failed) on the conversation page
* **Button events do not currently reach MaiAgent**: When customers tap Instagram FAQ or menu buttons, Meta sends a button event (postback) rather than a regular message. These events do not currently reach MaiAgent, do not appear in conversations, and receive no Agent reply. Typed direct messages are unaffected. For example, if an account has FAQ buttons and a customer taps “Business hours,” they receive no reply and no conversation appears in MaiAgent. Typing the question instead brings it in normally

## <mark style="color:blue;">Frequently Asked Questions</mark> <a href="#faq" id="faq"></a>

### Q: Why Is the Page List Empty After Authorization? <a href="#faq-empty-page-list" id="faq-empty-page-list"></a>

The Facebook account you signed in with does not have full control of the Page, or the Page was not selected during authorization. Check permissions using [Before You Connect](#pre-integration-checklist), then sign in again as a Page administrator and select the correct Page in the authorization window.

### Q: Why Does Saving Show “This Page Is Not Linked to an Instagram Account”? <a href="#faq-page-not-linked" id="faq-page-not-linked"></a>

The Page has not been linked to the Instagram professional account, or the Instagram account is still a personal account. Switch to a professional account in Instagram, link it to the Page, and authorize again.

### Q: Why Does Saving Show “This Instagram Account Is Already in Use”? <a href="#faq-account-already-used" id="faq-account-already-used"></a>

The same Instagram account is already connected to another channel in your organization. Delete the original channel, then create a new connection.

### Q: A User Sent a Direct Message, but MaiAgent Did Not Receive It. Why? <a href="#faq-no-incoming-message" id="faq-no-incoming-message"></a>

Check the following in order: in Meta Business Suite's <mark style="color:blue;">Conversation routing</mark>, this Instagram account's default routing app is MaiAgent; the test account was not already in a conversation in the old system before the switch and did not enter through an ad or link assigned to the old system (see [Configure Conversation Routing](#conversation-routing)); the Instagram account's message controls allow connected tools to access messages; the link between the Page and Instagram account is still valid; and the authorized Facebook account is still a Page administrator. If authorization has expired or Page permissions have been removed, delete the channel and connect it again.

### Q: Why Do Customers Still Receive Automatic Messages Such as “Our Team Will Reply During Business Hours”? <a href="#faq-meta-auto-reply" id="faq-meta-auto-reply"></a>

These messages come from Meta Business Suite's built-in automated replies and do not pass through MaiAgent, so they do not appear in MaiAgent's <mark style="color:blue;">All Conversations</mark>. Disabling MaiAgent's AI auto-reply schedule does not block them. In Meta Business Suite, go to <mark style="color:blue;">Inbox</mark> → <mark style="color:blue;">Automations</mark> and check <mark style="color:blue;">Away message</mark>, <mark style="color:blue;">Instant reply</mark>, <mark style="color:blue;">Frequently asked questions</mark>, and <mark style="color:blue;">Leads</mark> one by one. Turn off what you do not need and update anything you keep to reflect the current setup. For a scenario, see [FB Messenger: Customers Still Receive Automatic Messages](/maiagent-user-guide/en/build/choose-channel/fb.md#faq-meta-auto-reply).

### Q: Can Instagram and FB Messenger Use the Same Agent? <a href="#faq-share-agent" id="faq-share-agent"></a>

Yes. They are separate channels and can use the same Agent or have different Agents configured independently.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/instagram.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.