> 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/serve/choose-channel/instagram.md).

# Connect a Messaging Platform: Instagram

Connect an AI agent to Instagram Direct for a professional account, including prerequisites, the authorization process, and FAQs

The Instagram Direct connection is built on a Facebook Page. MaiAgent obtains authorization through the Page linked to the Instagram account, then uses the Page to receive and reply to Instagram Direct messages. The authorization process is the same as for [FB Messenger](/maiagent-user-guide/en/serve/choose-channel/fb.md), except 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**

* You have created an “AI agent” on the [MaiAgent platform](https://admin.maiagent.ai/).

**Instagram account preparation**

* The Instagram account has been switched to a **professional account** (business or creator account). Personal accounts cannot be connected.
* The Instagram account is linked to a Facebook Page. Complete the connection under <mark style="color:blue;">Settings → Business tools and controls → Linked accounts</mark> in the Instagram app, or under <mark style="color:blue;">Settings → Linked accounts</mark> on the Page.
* The Instagram account allows messages to be received (<mark style="color:blue;">Settings → Messages and story replies → Message controls → Allow access to messages through connected tools</mark>).

**Facebook permission preparation**

* The Facebook account used to log in has been invited to or has created a business portfolio and has full control.
* If the Page is already in the business portfolio: No additional changes are required.
* If the Page is not in the business portfolio: You must be an administrator of the Page and have 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). The creator automatically receives full control.

**How do I check whether I have full control?** Go to <mark style="color:blue;">Settings → Users → People</mark> in [Meta Business Suite](https://business.facebook.com/), then select your name to view your permissions. If you only have partial access, ask a member with full control of the portfolio to update your permissions. See [Meta's official instructions](https://www.facebook.com/business/help/442345745885606) for details.

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

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

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

## <mark style="color:blue;">Start Connecting</mark> <a href="#start-integration" id="start-integration"></a>

### 1. Open the messaging platform connection page <a href="#step-go-to-channel-page" id="step-go-to-channel-page"></a>

Select <mark style="color:blue;">Messaging Platforms</mark> from the menu on the left, click <mark style="color:blue;">Connect Messaging Platform</mark> in the upper-right corner, then select <mark style="color:blue;">Instagram</mark> on the platform selection page.

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

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

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

MaiAgent accesses only messages from 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>Log in with Facebook</p></figcaption></figure>

{% hint style="warning" %}
Make sure your browser allows pop-ups. Otherwise, it may block the Facebook login window. If the Page list is not updated after authorization, click <mark style="color:blue;">Reload</mark> in the upper-right corner of the <mark style="color:blue;">Instagram channel</mark> section to authorize it again.
{% endhint %}

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

| Field                       | Description                                                                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Messaging platform name** | Give this connection a name so you can identify it easily.                                                                                                                     |
| **AI agent**                | Select the AI agent that will reply to Instagram Direct 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) When enabled, you can configure one or more commands. When a user sends one of these commands in a direct message, a new conversation begins, such as “Start over.” |

{% hint style="info" %}
The list shows all Pages you have authorized. If the Page you select is not linked to an Instagram account, the error “This Page is not linked to an Instagram account” appears when you save. Return to Instagram or the Page settings, complete the connection, and 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 Platform</mark> to finish creating the connection. After the connection succeeds, MaiAgent automatically subscribes to message events for the Page through Meta. You do not need to configure a separate Webhook.

Use another Instagram account to send a test direct message to the professional account. If the AI agent replies normally, the connection was successful. You can also open this connection from the MaiAgent messaging platform list and view incoming direct messages under <mark style="color:blue;">All Conversations</mark>.

{% hint style="info" %}
After the connection succeeds, click Edit in the messaging platform list to configure additional options, including OCR, answering with the system time or sender name, handoff to a human agent, conversation tags, and access control. For details, see [Messaging Platform Settings Overview](/maiagent-user-guide/en/serve/platform-settings.md).
{% endhint %}

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

| Direction       | Supported content                                                                |
| --------------- | -------------------------------------------------------------------------------- |
| User → AI agent | Text, images, videos, voice messages, and stickers; OCR can be used with images. |
| AI agent → User | Text and images                                                                  |

## <mark style="color:blue;">FAQ</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 used to log in does not have full control of the Page, or the Page was not selected during authorization. Follow [Before You Connect](#pre-integration-checklist) to check the permissions, log in again as a Page administrator, and make sure the correct Page is selected in the authorization window.

### Q: Why does “This Page is not linked to an Instagram account” appear when I save? <a href="#faq-page-not-linked" id="faq-page-not-linked"></a>

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

### Q: Why does “This Instagram account is already in use” appear when I save? <a href="#faq-account-already-used" id="faq-account-already-used"></a>

The same Instagram account is already connected to another messaging platform in the organization. Delete the original messaging platform, then create it again.

### Q: Why hasn't MaiAgent received a user's direct message? <a href="#faq-no-incoming-message" id="faq-no-incoming-message"></a>

Check the following in order: the Instagram account's message controls allow connected tools to access messages; the connection between the Page and Instagram account is still active; and the authorized Facebook account is still an administrator of the Page. If the authorization has expired or the Page permission has been removed, delete the messaging platform and connect it again.

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

Yes. They are separate messaging platforms and can be linked to the same AI agent, or you can configure different options for each platform.


---

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