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

# 串接對話平台：Instagram

將 Agent 串接到 Instagram 專業帳號的私訊，前置條件、授權流程與常見問題

Instagram 私訊串接建立在 Facebook 粉絲專頁之上：MaiAgent 透過與 Instagram 帳號連結的粉絲專頁取得授權，再由該粉專代收與代回 Instagram 私訊。授權流程與 [FB Messenger](/build/choose-channel/fb.md) 相同，差別在於粉專必須先連結 Instagram 專業帳號。

## <mark style="color:blue;">串接前確認</mark> <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

**MaiAgent 準備**

* 已在 [MaiAgent 平台](https://admin.maiagent.ai/)上建立好一個「AI 助理」

**Instagram 帳號準備**

* Instagram 帳號已切換為**專業帳號**（商業帳號或創作者帳號），個人帳號無法串接
* 該 Instagram 帳號已連結到一個 Facebook 粉絲專頁（在 Instagram App 的 <mark style="color:blue;">設定 → 商家工具與控制項 → 連結的帳號</mark>，或在粉絲專頁的 <mark style="color:blue;">設定 → 已連結的帳號</mark> 完成連結）
* 該 Instagram 帳號已允許接收訊息（<mark style="color:blue;">設定 → 訊息與限時動態回覆 → 訊息控制項 → 允許使用連結工具存取訊息</mark>）

**Facebook 權限準備**

* 用來登入的 Facebook 帳號已被邀請或建立過商家資產管理組合，並擁有「完整控制權限」
* 如果粉專已在商家資產管理組合下：無需額外調整
* 如果粉專不在商家資產管理組合下：必須是該粉絲專頁的管理人員且擁有完整控制權限

{% hint style="info" %}
**還沒有商家資產管理組合？** 請先依 Meta 官方說明[建立商家資產管理組合](https://www.facebook.com/business/help/1710077379203657)，建立者會自動擁有完整控制權限。

**如何確認自己有完整控制權限？** 到 [Meta Business Suite](https://business.facebook.com/) 的 <mark style="color:blue;">設定 → 用戶 → 人員</mark>，點選自己的名字查看權限。若只有部分存取權限，請組合內有完整控制權限的成員協助調整，權限說明詳見 [Meta 官方說明](https://www.facebook.com/business/help/442345745885606)。

**粉專要先加進商家資產管理組合嗎？** 不一定要。授權時可以直接認領粉專；若想事先整理好，也可以依 [Meta 官方說明](https://www.facebook.com/business/help/720478807965744)把粉專加進組合。

**Instagram 帳號要加進商家資產管理組合嗎？** 不需要。MaiAgent 透過粉專取得連結的 Instagram 帳號，只要 Instagram 專業帳號已連結該粉專即可。
{% endhint %}

{% hint style="warning" %}
**Instagram 已接過其他客服系統？** 串接完成後還要到 Meta Business Suite 把 Instagram 帳號「對話轉送」的預設 app 改成 MaiAgent，否則私訊會繼續由原本的 app 處理，見 [設定對話轉送](#conversation-routing)。整套搬家流程見 [從其他客服系統搬到 MaiAgent](/build/choose-channel/migrate-from-other-platform.md)。
{% endhint %}

{% hint style="warning" %}
一個 Instagram 帳號只能串接到一個對話平台。若要換綁到其他 Agent，請先刪除原本的對話平台再重新串接。
{% endhint %}

## <mark style="color:blue;">開始串接</mark> <a href="#start-integration" id="start-integration"></a>

### 1. 進入串接對話平台頁面 <a href="#step-go-to-channel-page" id="step-go-to-channel-page"></a>

在左側選單點選 <mark style="color:blue;">對話平台</mark>，點擊右上角 <mark style="color:blue;">串接對話平台</mark>，在平台選擇頁面點選 <mark style="color:blue;">Instagram</mark>。

### 2. 登入 Facebook 並授權 <a href="#step-facebook-login" id="step-facebook-login"></a>

點擊 <mark style="color:blue;">Facebook 登入</mark>，以管理該粉專的 Facebook 帳號登入。授權視窗會依序要求：

1. 選擇要授權的商家資產管理組合
2. 選擇（認領）已連結 Instagram 帳號的粉絲專頁
3. 確認授權

MaiAgent 只會存取您授權的粉絲專頁與其連結 Instagram 帳號的訊息，不會存取您的個人訊息。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-dc446ea48022138a20907b9d1282def9e546042a%2Fimage%20(5)%20(1)%20(1)%20(1).png?alt=media&amp;token=87122f07-52cf-4f0c-8cea-8bf5b04aa3d3" alt=""><figcaption><p>Facebook 登入</p></figcaption></figure>

{% hint style="warning" %}
請確認瀏覽器允許彈出視窗，否則 Facebook 登入視窗可能被封鎖。若授權後粉專清單沒有更新，可點擊 <mark style="color:blue;">Instagram 頻道</mark> 區塊右上角的 <mark style="color:blue;">重新載入</mark> 重新授權一次。
{% endhint %}

### 3. 基本設定 <a href="#step-basic-settings" id="step-basic-settings"></a>

| 欄位         | 說明                                                     |
| ---------- | ------------------------------------------------------ |
| **對話平台名稱** | 為此串接取一個名稱，方便辨識                                         |
| **AI 助理**  | 選擇要回覆 Instagram 私訊的 Agent                              |
| **選擇粉專**   | 從清單中選擇已連結 Instagram 帳號的粉絲專頁，系統會自動取得該粉專連結的 Instagram 帳號 |
| **啟用重置命令** | （選填）開啟後可設定一個或多個指令，使用者在私訊中送出該指令時會重新開始一段新對話，例如「重新開始」     |

{% hint style="info" %}
清單列出的是您授權的所有粉絲專頁。若選到的粉專沒有連結 Instagram 帳號，儲存時會出現「此 Page 沒有連結 Instagram 帳號」的錯誤，請回到 Instagram 或粉專設定完成連結後再試一次。
{% endhint %}

### 4. 儲存並確認串接結果 <a href="#step-verify-integration" id="step-verify-integration"></a>

點擊 <mark style="color:blue;">串接對話平台</mark> 完成建立。串接成功後，MaiAgent 會自動向 Meta 訂閱該粉專的訊息事件，不需要另外設定 Webhook。

用另一個 Instagram 帳號私訊該專業帳號送出測試訊息，Agent 如可以正常回覆，表示串接已成功。您也可以在 MaiAgent 的對話平台列表點進此串接，於 <mark style="color:blue;">所有對話</mark> 中看到進線的私訊。

{% hint style="info" %}
串接成功後，可在對話平台列表點擊編輯，進一步設定功能選項（OCR 辨識、使用系統時間或傳送者名稱回答、客服轉真人、對話標籤、權限控管等），詳見[對話平台設定總覽](/build/conversation-settings/platform-settings.md)。
{% endhint %}

## <mark style="color:blue;">Instagram 已接其他客服系統時：設定對話轉送</mark> <a href="#conversation-routing" id="conversation-routing"></a>

Instagram 帳號若已經接過其他客服或行銷 app（例如 Omnichat、Messenger by SHOPLINE），Meta 會把私訊交給「對話轉送」設定的**預設轉送 app** 處理。MaiAgent 不是預設 app 時，串接雖然顯示成功，私訊仍由原本的 app 處理：MaiAgent 收不到，Agent 也不會回覆。

串接完成後，請對粉專有完整控制權限的管理員到 [Meta Business Suite](https://business.facebook.com/) 把預設 app 改成 MaiAgent：

1. 點 <mark style="color:blue;">設定</mark> → <mark style="color:blue;">整合工具</mark> → <mark style="color:blue;">對話轉送</mark>
2. 選擇這個 Instagram 帳號，點 <mark style="color:blue;">設定</mark>
3. <mark style="color:blue;">預設轉送 app</mark> 選 <mark style="color:blue;">MaiAgent</mark>，點 <mark style="color:blue;">繼續</mark>

設定時注意：

* **Messenger 與 Instagram 要各設一次**：只改了粉專（Messenger）的設定，Instagram 私訊仍會交給原本的 app，反之亦然。Messenger 的設定見 [FB Messenger：設定對話轉送](/build/choose-channel/fb.md#conversation-routing)。
* **原本的 app 不必移除**：預設 app 決定的是「沒有其他 app 正在處理」的對話交給誰，原本的 app 留著不影響新對話進 MaiAgent。
* **新對話立即生效，進行中的對話不一定**：改完後，新客人或已經一段時間沒互動的客人傳來的私訊會交給 MaiAgent。但切換前正在原本 app 裡對話的客人，這段對話仍由原本的 app 掌控，續傳的私訊會繼續進原本的系統，要等原本的 app 釋出對話，或客人約 24 小時沒再傳訊（原本的 app 可能把這段時間延長到最多 7 天）後，才會改交給 MaiAgent。改之前的訊息與對話紀錄留在原本的系統，不會帶過來。
* **廣告與專屬連結另有指定**：原本的 app 若替導向 Instagram 私訊的廣告或連結指定了負責的 app，從這些入口進來的對話可能仍交給原本的 app，不看預設 app。請到原本的 app 或廣告設定改成 MaiAgent，或先停用這些入口。
* **切換後分別確認**：用一個從沒傳過私訊的帳號測新對話；切換前後幾天仍回頭看原本的系統，確認進行中對話的續傳私訊都處理到；有在跑的廣告或連結，從那個入口實際傳一則確認進到 MaiAgent。需要讓進行中的對話馬上轉過來，請原本的系統廠商把對話釋出或交接。
* **退回**：把預設轉送 app 改回原本的 app。退回同樣只對新對話與一段時間沒互動的對話立即生效，已經在 MaiAgent 進行中的對話，續傳的私訊仍會進 MaiAgent，要等約 24 小時沒互動後才回到原本的 app，這段期間請客服繼續在 MaiAgent 回覆。MaiAgent 的對話平台可以先保留。

例如一家服飾品牌把 Messenger 和 Instagram 一起搬到 MaiAgent，對話轉送只改了粉專，結果 Messenger 的測試訊息進了 MaiAgent，Instagram 的測試私訊卻沒有。回到 <mark style="color:blue;">對話轉送</mark> 改選 Instagram 帳號、把預設轉送 app 也設成 MaiAgent 後，Instagram 私訊就進來了。

{% hint style="info" %}
「對話轉送」在英文介面是 Conversation routing，MaiAgent 對話平台設定頁的提醒稱為「對話路由」，指的都是這個設定；選單位置可能隨 Meta 改版調整，運作方式見 Meta 官方說明 [Conversation Routing for Instagram](https://developers.facebook.com/docs/messenger-platform/instagram/features/conversation-routing)。設定前請先記下原本的預設 app（原本沒有設定也記下來），退回時要用。
{% endhint %}

## <mark style="color:blue;">支援的訊息類型</mark> <a href="#supported-message-types" id="supported-message-types"></a>

| 方向          | 支援內容                        |
| ----------- | --------------------------- |
| 使用者 → Agent | 文字、圖片、影片、語音、貼圖；圖片可搭配 OCR 辨識 |
| Agent → 使用者 | 文字、圖片                       |

* **Markdown 自動轉純文字**：Instagram 不會渲染 Markdown，Agent 回覆中的標題、粗斜體、連結、表格等語法在送出前會自動轉成純文字（連結變成「文字 網址」），真人客服打的字不受影響，見 [訊息內容渲染優化：通訊軟體通道](/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)
* **連續訊息合併成一輪**：使用者連續傳多張圖片、或先傳圖再打字時，Agent 會等這一串訊息到齊（只含圖片的訊息，最後一則後約 4 秒沒有新訊息才回答，最長約 20 秒，收到文字就立刻回）後一次回答；同一對話一次只處理一輪
* **24 小時回覆期限**：Meta 只允許在使用者最後一則訊息後 24 小時內回覆，超過期限送出的訊息會在對話頁標示 [未送達](/serve/daily-operations/reply.md#delivery-failed)
* **按鈕事件目前不會進 MaiAgent**：客人點 Instagram 的常見問題按鈕或選單按鈕時，Meta 送出的是按鈕事件（postback），不是一般訊息。這類事件目前不會進到 MaiAgent，對話中看不到，Agent 也不會回覆；客人打字傳的私訊不受影響。例如帳號原本設了常見問題按鈕，客人點了「營業時間」後沒有收到回覆，MaiAgent 也沒有這筆對話，客人改用打字詢問就會正常進線

## <mark style="color:blue;">常見問題</mark> <a href="#faq" id="faq"></a>

### Q：授權後粉專清單是空的？ <a href="#faq-empty-page-list" id="faq-empty-page-list"></a>

登入的 Facebook 帳號沒有該粉專的完整控制權限，或授權時沒有勾選該粉專。請先依[串接前確認](#pre-integration-checklist)檢查權限，再以粉專管理員身分重新登入，並在授權視窗中確認勾選正確的粉專。

### Q：儲存時顯示「此 Page 沒有連結 Instagram 帳號」？ <a href="#faq-page-not-linked" id="faq-page-not-linked"></a>

粉專與 Instagram 專業帳號尚未連結，或 Instagram 帳號仍是個人帳號。請先在 Instagram 切換為專業帳號並連結該粉專，再重新授權一次。

### Q：儲存時顯示「此 Instagram 帳號已被使用」？ <a href="#faq-account-already-used" id="faq-account-already-used"></a>

同一個 Instagram 帳號已串接到組織內另一個對話平台。請先刪除原本的對話平台，再重新建立。

### Q：使用者私訊了，但 MaiAgent 沒有收到？ <a href="#faq-no-incoming-message" id="faq-no-incoming-message"></a>

請依序確認：Meta Business Suite 的 <mark style="color:blue;">對話轉送</mark> 中，這個 Instagram 帳號的預設轉送 app 是 MaiAgent，且測試帳號不是切換前就在舊系統對話中、也不是從舊系統指定的廣告或連結入口進來（見 [設定對話轉送](#conversation-routing)）、Instagram 帳號的訊息控制項已允許連結工具存取訊息、粉專與 Instagram 帳號的連結仍然有效、授權的 Facebook 帳號仍是粉專管理員。若是授權過期或粉專權限被移除，請刪除對話平台後重新串接。

### Q：客人還收到「小編將於上班時間回覆」之類的自動訊息？ <a href="#faq-meta-auto-reply" id="faq-meta-auto-reply"></a>

這類訊息是 Meta Business Suite 原生的自動回覆送出的，不經過 MaiAgent，所以不會出現在 MaiAgent 的 <mark style="color:blue;">所有對話</mark>；把 MaiAgent 的 AI 自動回覆時段關掉也擋不掉。到 Meta Business Suite 的 <mark style="color:blue;">收件匣</mark> → <mark style="color:blue;">自動回覆</mark>，逐項檢查 <mark style="color:blue;">離線自動回覆訊息</mark>、<mark style="color:blue;">自動回覆</mark>、<mark style="color:blue;">常見問題</mark>、<mark style="color:blue;">潛在顧客</mark>，不需要的關閉，要保留的改成符合現況的內容。情境例子見 [FB Messenger：客人還收到自動訊息](/build/choose-channel/fb.md#faq-meta-auto-reply)。

### Q：Instagram 與 FB Messenger 可以共用同一個 Agent 嗎？ <a href="#faq-share-agent" id="faq-share-agent"></a>

可以。兩者是各自獨立的對話平台，可以綁定同一個 Agent，也可以各自設定不同的功能選項。


---

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