> 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 Instagram professional account messages, including prerequisites, authorization, and troubleshooting

Instagram messaging 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 messages. The authorization process is the same as for [FB Messenger](https://docs.maiagent.ai/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>

**Prepare MaiAgent**

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

**Prepare your Instagram account**

* 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 from connected tools</mark>)

**Prepare Facebook permissions**

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

{% hint style="info" %}
**Don't 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 receives 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 adjust your permissions. See [Meta's official documentation](https://www.facebook.com/business/help/442345745885606) for details.

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

**Do I need to add the Instagram account to a business portfolio?** No. MaiAgent obtains the linked Instagram account through the Page. You only need to link the Instagram professional account to that Page.
{% endhint %}

{% hint style="warning" %}
**Is Instagram already connected to another customer service system?** After connecting, go to Meta Business Suite and change the Instagram account's default app under Conversation routing to MaiAgent. Otherwise, the original app will continue handling messages. See [Set up conversation routing](#conversation-routing). For the full migration process, see [Migrate from another customer service system to MaiAgent](https://docs.maiagent.ai/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 messaging channel. To switch to another Agent, delete the original messaging channel first, then reconnect.
{% 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;">Messaging Channels</mark> in the left menu, click <mark style="color:blue;">Connect Messaging Channel</mark> in the upper right, then select <mark style="color:blue;">Instagram</mark> on the platform selection page.

### 2. Log in with Facebook and authorize access <a href="#step-facebook-login" id="step-facebook-login"></a>

Click <mark style="color:blue;">Facebook Login</mark> and log 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" %}
Make sure your browser allows pop-ups, or it may block the Facebook login window. 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. Configure basic settings <a href="#step-basic-settings" id="step-basic-settings"></a>

| Field                      | Description                                                                                                                                                                                                                                                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Messaging Channel Name** | Give this connection a recognizable name                                                                                                                                                                                                                                                                             |
| **AI Assistant**           | Select the Agent that will reply to Instagram messages                                                                                                                                                                                                                                                               |
| **Select Page**            | Select the Page linked to the Instagram account from the list. The system automatically retrieves the Instagram account linked to that Page                                                                                                                                                                          |
| **Enable Reset Commands**  | (Optional) Enable this to add one or more command phrases (such as “Start over”). When a user's Instagram message exactly matches one of these phrases, a new conversation opens for that user. The command itself receives no reply; the AI responds in the new conversation when the user sends their next message |

{% hint style="info" %}
The list shows all Pages you authorized. If the selected Page has no linked Instagram account, saving displays the error “This Page is not linked to an Instagram account.” Complete the link in Instagram or the 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 Messaging Channel</mark> to finish creating the connection. Once connected, MaiAgent automatically subscribes to the Page's message events through Meta. No separate Webhook setup is required.

Send a test 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 MaiAgent's messaging channel list and view incoming messages under <mark style="color:blue;">All Conversations</mark>.

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

## <mark style="color:blue;">If Instagram Uses Another Customer Service System: Set Up Conversation Routing</mark> <a href="#conversation-routing" id="conversation-routing"></a>

If your Instagram account has been connected to another customer service or marketing app (such as Omnichat or Messenger by SHOPLINE), Meta sends messages to the **default routing app** configured under Conversation routing. When MaiAgent is not the default app, the connection may show as successful, but the original app still handles 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>, then click <mark style="color:blue;">Continue</mark>

Keep the following in mind:

* **Configure Messenger and Instagram separately**: Changing only the Page's (Messenger) settings still sends Instagram messages to the original app, and vice versa. For Messenger, see [FB Messenger: Set up conversation routing](https://docs.maiagent.ai/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 receives conversations that no other app is currently handling. Keeping the original app does not prevent new conversations from reaching MaiAgent.
* **New conversations switch immediately; active conversations may not**: After the change, 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, and subsequent messages continue going to the original system. They switch to MaiAgent after the original app releases the conversation or the customer has not sent a message for about 24 hours (the original app may extend this to up to 7 days). Earlier messages and conversation history remain in the original system and are not transferred.
* **Ads and dedicated links may have separate assignments**: If the original app has assigned a specific app to ads or links that lead to Instagram messaging, conversations from those entry points may still go to the original app regardless of the default. Change the assignment to MaiAgent in the original app or ad settings, or disable those entry points first.
* **Verify each case after switching**: Test new conversations with an account that has never sent a message. Keep checking the original system for a few days around the switch to ensure follow-up messages in active conversations are handled. For running ads or links, send an actual message through each entry point to confirm it reaches MaiAgent. If active conversations must transfer immediately, ask the original system provider to release or hand them over.
* **Switching back**: Change the default routing app back to the original app. This also takes immediate effect only for new conversations and those inactive for a while. Follow-up messages in conversations already active in MaiAgent still go to MaiAgent until there has been no interaction for about 24 hours. During this period, support staff should continue replying in MaiAgent. You can keep the MaiAgent messaging channel for now.

For example, a clothing brand moves both Messenger and Instagram to MaiAgent but changes conversation routing only for the Page. Its Messenger test message reaches MaiAgent, but its Instagram test message does not. After returning to <mark style="color:blue;">Conversation routing</mark>, selecting the Instagram account, and setting its default routing app to MaiAgent too, Instagram messages start arriving.

{% hint style="info" %}
The English interface calls this setting “Conversation routing.” The reminder on MaiAgent's messaging channel settings page calls it “conversation routing”; both refer to the same setting. Menu locations may change as Meta updates its interface. For details on how it works, see Meta's official [Conversation Routing for Instagram](https://developers.facebook.com/docs/messenger-platform/instagram/features/conversation-routing) documentation. Before changing the setting, record the original default app (including if none was set), so you can switch back.
{% 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 recognition |
| Agent → User | Text and images                                                                    |

* **Automatic Markdown to plain text conversion**: Instagram does not render Markdown. Syntax such as headings, bold, italics, links, and tables in Agent replies is automatically converted to plain text before sending (links become “text URL”). Text entered by human support staff is unaffected. See [Message Rendering Optimization: Messaging Channels](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)
* **Consecutive messages are combined into one turn**: When a user sends multiple images in a row, or sends images followed by text, the Agent waits for the sequence to arrive before replying once (for image-only messages, it replies after about 4 seconds without a new message after the last one, waiting up to about 20 seconds; text triggers an immediate reply). Only one turn is processed at a time per conversation
* **24-hour reply window**: Meta only allows replies within 24 hours of the user's last message. Messages sent after this window are marked [Undelivered](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/reply.md#delivery-failed) on the conversation page
* **Button events do not currently reach MaiAgent**: When a customer clicks an Instagram FAQ or menu button, Meta sends a button event (postback), rather than a regular message. These events do not currently reach MaiAgent, appear in conversations, or trigger Agent replies. Messages typed by customers are unaffected. For example, if an account has an FAQ button for “Business hours,” clicking it produces no reply or conversation in MaiAgent, but typing the question sends it through 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 logged in with lacks full control of the Page, or you did not select that Page during authorization. Check permissions using [Before You Connect](#pre-integration-checklist), then log 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 is not yet 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, then 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 messaging channel in your organization. Delete the original messaging channel, then create the connection again.

### Q: Why doesn't MaiAgent receive a user's message? <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 an active conversation in the old system before the switch and did not enter through an ad or link assigned to the old system (see [Set up conversation routing](#conversation-routing)); Instagram'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 were removed, delete the messaging channel and reconnect.

### 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 native automated responses and do not pass through MaiAgent, so they do not appear in MaiAgent's <mark style="color:blue;">All Conversations</mark>. Turning off MaiAgent's AI automatic reply hours does not stop them either. In Meta Business Suite, go to <mark style="color:blue;">Inbox</mark> → <mark style="color:blue;">Automations</mark> and review <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> individually. Turn off any you do not need and update those you keep to reflect your current setup. For an example, see [FB Messenger: Customers still receive automatic messages](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/fb.md#faq-meta-auto-reply).

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

Yes. They are separate messaging channels that can use the same Agent, with different feature settings for each.


---

# 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.
