> 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/fb.md).

# 串接對話平台：FB Messenger

將 Agent 串接到 Facebook 粉絲專頁的 Messenger，前置權限、授權流程與常見問題

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

**MaiAgent 準備**

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

**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)把粉專加進組合。
{% endhint %}

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

{% hint style="warning" %}
一個粉絲專頁只能串接到一個對話平台。若要換綁到其他 Agent，請先刪除原本的對話平台再重新串接。要串接同一粉專連結的 Instagram 私訊，請另外建立 [Instagram](/build/choose-channel/instagram.md) 對話平台。
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-d6d1aa18fa70dede47b7daeaed0a4f0eadf3febf%2Fimage%20(12)%20(1).png?alt=media&amp;token=b74d95f5-058c-4543-9f6d-1a199466313b" alt=""><figcaption></figcaption></figure>

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

### 1. 到 MaiAgent 的對話平台頁面，點選「串接對話平台」 <a href="#step-go-to-maiagent-channel-page" id="step-go-to-maiagent-channel-page"></a>

a. 點選右上角<mark style="color:blue;">串接對話平台</mark>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-45051526831861d07352f6b1084732e923c9fa5b%2Fimage%20(102).png?alt=media&amp;token=79b5d3df-f535-41a3-9d1b-4405925b1bd0" alt=""><figcaption></figcaption></figure>

b. 選擇 Messenger

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-54c2a072dbdd6e95a23e672d6d7779e764381955%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-21%20122626.png?alt=media" alt=""><figcaption></figcaption></figure>

c. 點擊 <mark style="color:blue;">Facebook 登入</mark>，以管理該粉專的 Facebook 帳號登入。MaiAgent 只會存取您授權的粉絲專頁訊息，不會存取您的個人訊息。

{% hint style="warning" %}
請確認瀏覽器允許彈出視窗，否則 Facebook 登入視窗可能被封鎖。
{% endhint %}

<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></figcaption></figure>

### 2. 選擇商家，並選擇（認領）粉專。 <a href="#step-select-business-and-page" id="step-select-business-and-page"></a>

在 Facebook 授權視窗中，先選擇要授權的商家資產管理組合，再勾選要託管（認領）的粉絲專頁。

確定授權，建立成功後即完成託管。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-711739d48ba4820003d4771f15abed0475eff185%2Fimage%20(13)%20(1).png?alt=media&amp;token=59c3b2d7-8fe1-4aa6-aa91-7a2ba542cf14" alt=""><figcaption></figcaption></figure>

### 3. Agent 設定 <a href="#step-ai-agent-settings" id="step-ai-agent-settings"></a>

| 欄位         | 說明                                                                 |
| ---------- | ------------------------------------------------------------------ |
| **對話平台名稱** | 為此串接取一個名稱，方便辨識                                                     |
| **AI 助理**  | 選擇要回覆 Messenger 訊息的 Agent                                          |
| **選擇粉專**   | 從 <mark style="color:blue;">Messenger 頻道</mark> 區塊的清單中選擇您剛剛認領的粉絲專頁 |
| **啟用重置命令** | （選填）開啟後可設定一個或多個指令，使用者在 Messenger 送出該指令時會重新開始一段新對話，例如「重新開始」         |

{% hint style="info" %}
若授權後粉專清單沒有更新，可點擊 <mark style="color:blue;">Messenger 頻道</mark> 區塊右上角的 <mark style="color:blue;">重新載入</mark> 重新授權一次。
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-0bd1984760eed7ad89aaf3ddcfb63d6aaab0c98b%2Fimage%20(106).png?alt=media&amp;token=7bb429b8-f373-4960-8fda-471600c2fc0c" alt=""><figcaption></figcaption></figure>

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

接著您可以在 MaiAgent 的內部對話試著針對該對話平台送出一個測試訊息，Agent 如可以正常回覆對話，表示串接已成功。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-1542ac8f364fb8abc6d3679953254b1d50961586%2Fimage%20(14)%20(1).png?alt=media&amp;token=e846076c-ab58-47c8-b6fb-f9e5907de3cb" alt=""><figcaption></figcaption></figure>

您也可以到該粉專開啟 Agent 對話，送出測試訊息，機器人如可以正常回覆對話，表示串接已成功。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-74d2aed8c0d151071b721aba80dbfe3627258b24%2Fimage%20(10)%20(1)%20(1).png?alt=media&amp;token=8238d2a2-7196-4b6e-ab0e-a17fa05dc641" alt=""><figcaption></figcaption></figure>

串接成功後，MaiAgent 會自動向 Meta 訂閱該粉專的訊息事件，不需要另外設定 Webhook。

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

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

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

例如一家電商的粉專原本接 Omnichat。管理員在 MaiAgent 串接 Messenger 後，用個人帳號傳訊測試，MaiAgent 的 <mark style="color:blue;">所有對話</mark> 一直沒有進線，Omnichat 那邊卻收到了。到 Business Suite 的 <mark style="color:blue;">對話轉送</mark> 一看，預設轉送 app 仍是 Omnichat；改成 MaiAgent 後，管理員改用另一個從沒傳過訊息的帳號再傳一則，訊息就進到 MaiAgent；但原本已在 Omnichat 跟客服聊到一半的客人續傳的訊息仍進 Omnichat，客服當天繼續在 Omnichat 回完這幾位，隔天再看就都進 MaiAgent 了。

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

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

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

* **Markdown 自動轉純文字**：Messenger 不會渲染 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**：客人點 Messenger 的「立即開始」（Get Started）按鈕或選單按鈕時，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：儲存時顯示「此頁面 ID 已被使用」？ <a href="#faq-page-already-used" id="faq-page-already-used"></a>

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

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

粉專接過其他客服系統時，先到 Meta Business Suite 的 <mark style="color:blue;">對話轉送</mark> 確認預設轉送 app 是 MaiAgent，見 [設定對話轉送](#conversation-routing)；預設 app 已是 MaiAgent 卻仍沒收到，可能是這位客人切換前就在舊系統對話、還由舊系統掌控，或是從舊系統指定的廣告／連結入口進來，請改用沒傳過訊息的帳號再測一次。

接著確認授權的 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>，不需要的關閉，要保留的改成符合現況的內容。

例如品牌改成只用真人客服後，客服人員發現客人晚上傳訊仍會立刻收到「小編將於上班時間回覆」，但 MaiAgent 的對話紀錄裡沒有這則。這是 Business Suite 的離線自動回覆訊息，到 <mark style="color:blue;">收件匣</mark> → <mark style="color:blue;">自動回覆</mark> 關閉後就不會再送出。Instagram 私訊的自動回覆也在同一處設定。

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

可以。兩者是各自獨立的對話平台，可以綁定同一個 Agent，也可以各自設定不同的功能選項。Instagram 的串接方式請見[串接對話平台：Instagram](/build/choose-channel/instagram.md)。

### Q：如何移除（取消串接）Messenger？ <a href="#faq-disconnect" id="faq-disconnect"></a>

到 <mark style="color:blue;">對話平台</mark> 列表，在該 Messenger 平台的操作欄點 <mark style="color:blue;">刪除</mark> 並確認（沒有刪除權限時圖示會停用）。刪除後 MaiAgent 不再接收與回覆這個粉專的訊息；需要保留對話紀錄的，請先在 <mark style="color:blue;">所有對話</mark> 匯出。MaiAgent 不會替您收回 Facebook 端的授權，要徹底解除請再到該粉絲專頁的設定移除對 MaiAgent 應用程式的授權。之後要重新串接，依 [開始串接](#start-integration) 重做一次即可。


---

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