洽談外掛程式

本文件說明如何以程式設計的方式將洽談外掛程式新增至網站上的 Messenger 體驗。

如果您想使用 Meta Business Suite 將洽談外掛程式新增至您的網頁（推薦），請造訪 Meta 企業商家使用說明以取得詳細資訊。

運作方式

在網頁上安裝 Facebook JavaScript SDK 時，洽談外掛程式將轉譯在網頁上。桌上型電腦和手機預設會顯示問候對話方塊，用戶可以點擊關閉按鈕，將對話方塊視窗縮到最小。您可以自訂外掛程式的問候語、外觀（例如顏色），以及訊息傳送體驗（例如功能表和快速回覆）。快取對話方塊狀態（最大化或最小化），並在連線階段之間持續存在。

登入

如果用戶已登入 Facebook，外掛程式將顯示「以 [名稱] 的身分繼續」和「以訪客身分繼續」按鈕。如果用戶尚未登入 Facebook，外掛程式將顯示「登入 Messenger」和「以訪客身分繼續」按鈕。

Webhook 通知

用戶點擊外掛程式以開始或繼續與您的企業聊天時，將向您的伺服器傳送一個 Webhook 通知，其中包含：

• 有關此用戶的資訊，例如粉絲專頁範圍編號（PSID）或用戶參考編號
• 將訊息的來源標識為洽談外掛程式
• 包含在通知中的轉介資訊

如果您在外掛程式中實作歡迎畫面 ，且用戶點擊「開始使用」按鈕以開始與您的企業對話，系統將傳送 messaging_postbacks Webhook 通知到您的伺服器。然後，您的企業可以使用用戶參考編號在 24 小時標準訊息期間內向用戶傳送訊息。

現有對話

如果用戶目前與您的企業有對話，對話記錄將自動載入到外掛程式。用戶繼續對話時，無論是傳送訊息、點擊按鈕或執行您在對話中實作的其他動作，都會傳送 messaging Ｗebhook 通知到您的伺服器，如果包含轉介資訊，則會傳送 messaging_referral Webhook 通知。然後，您的企業可以使用 PSID 在 24 小時標準訊息期間內向用戶傳送訊息。

洽談外掛程式支援的訊息類型

外掛程式不支援：

準備工作

必備資料：

• pages_messaging 權限
• 可在 Facebook 粉絲專頁執行 MODERATE 任務之用戶要求的粉絲專頁存取權杖
• 連結至訂閱 messaging、messaging_postbacks 和 messaging_referrals Webhooks 欄位的 Facebook 粉絲專頁的應用程式
• 使用 Messenger 個人檔案 API 或 Meta Business Suite，將網站的網域加入許可清單

《Meta 商業工具使用條款》適用於使用洽談外掛程式聯繫的情況。

限制

• 在成功實作洽談外掛程式之前，您的網站必須已上線或列入許可清單
• 如果您企業的 Facebook 粉絲專頁在「粉絲專頁」設定中已設定年齡或國家／地區限制，當用戶瀏覽您的網站時，若未登入其 Facebook 帳號，將不會顯示洽談外掛程式。
• 沒有為 Safari 12+ 和 Firefox 瀏覽器快取問候對話方塊

新增洽談外掛程式

步驟 1：新增 SDK

在您想要呈現外掛程式的網站的每個網頁上，加入 Facebook JavaScript SDK。

<!-- Messenger Chat Plugin Code --> <div id="fb-root"></div> <div id="fb-customer-chat" class="fb-customerchat"></div> <script> var chatbox = document.getElementById('fb-customer-chat'); chatbox.setAttribute("page_id", "PAGE-ID"); chatbox.setAttribute("attribution", "biz_inbox"); </script> <script> window.fbAsyncInit = function() { FB.init({ xfbml : true, version : 'API-VERSION' }); }; (function(d, s, id) { var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; js.src = 'https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js'; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'facebook-jssdk')); </script> 

步驟 2：自訂外掛程式

使用 API

傳送 POST 要求至 /PAGE-ID/chat_plugin 端點，以自訂外掛程式的問候語、色彩、圖示等等。

要求範例

curl -i -X POST "https://graph.facebook.com/v19.0/PAGE-ID/chat_plugin
    ?welcome_screen_greeting:YOUR-WELCOME-TEXT
    &theme_color:553399
    &entry_point_icon:MESSENGER-ICON
    &entry_point_label:CHAT
    &access_token=PAGE-ACCESS-TOKEN"

請瀏覽洽談外掛程式參考資料 ，以取得可用來自訂外掛程式之欄位的詳細資訊。

使用 HTML 屬性

我們建議您只將此方法用於透過粉絲專頁設定的設定工具或 API 無法使用的自訂項目。

Webhooks 通知

用戶傳送訊息給您的應用程式時，系統會傳送 Webhook 通知到您的伺服器。

現有對話

用戶向與您企業的現有對話傳送訊息時，系統會傳送 messaging Webhook 通知。通知會包含用戶的粉絲專頁範圍編號，而 tags 物件的 source 參數會設為 customer_chat_plugin。

訊息通知

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "PSID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

訊息轉介通知

如果您為洽談外掛程式設定 ref 屬性，系統將傳送 messaging_referrals Webhook 通知到您的伺服器。

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598385735,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598385735,
                    "sender": {
                        "user_ref":"USER-REFERENCE-ID"
                    },
                    "referral": {
                        "ref": "REF-PARAMETER-INFORMATION",
                        "source": "CUSTOMER_CHAT_PLUGIN",
                        "type": "OPEN_THREAD",
                        "referer_uri": "REFERRAL-URI"
                    }
                }
            ]
        }
    ]
}

新對話

用戶透過點擊外掛程式歡迎畫面中的「開始使用」按鈕開始對話時，系統將傳送 messaging_postbacks Webhook 通知。

訊息回傳通知

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "user_ref": "USER-REFERENCE-ID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "postback":{
                        "title": "TITLE-FOR-THE-CTA",  
                        "payload": "PAYLOAD-DEFINED-BY-CTA",
                        "referral": {
                            "ref": "ADDITIONAL-INFORMATION",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                    }
                }
            ]
        }
    ]
}

行銷訊息選擇接收要求

請瀏覽我們的行銷訊息指南 ，瞭解如何建立行銷訊息選擇接收要求。

限制

洽談外掛程式的行銷訊息僅支援最新消息及促銷活動主題。

訊息選擇接收通知

當用戶選擇接收您企業發出的行銷訊息時，系統會傳送 messaging_optins Webhook 通知到您的伺服器。

"object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": TIMESTAMP,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": TIMESTAMP,
                    "optin": {
                        "type": "notification_messages",
                        "payload": "empty_payload",
                        "notification_messages_token": "NOTIFICATION-MESSAGE-TOKEN",
                        "notification_messages_frequency": "MESSAGE-FREQUENCY",
                        "topic": "NOTIFICATION-MESSAGE-TOPIC",
                        "token_expiry_timestamp": EXPIRATION-DATE-TIMESTAMP,
                        "ref": "ADDITIONAL-INFORMATION",
                        "user_token_status": "NOT_REFRESHED",
                        "notification_messages_status": "RESUME_NOTIFICATIONS"
                    }
                }
            ]
        }
    ]
}

您可以將 notification_messages_token 值設為 recipient 物件中的編號值，以傳送行銷訊息給用戶。

疑難排解提示

• 拒絕顯示……

  • 確認您的網域已加入許可清單
  • 確認已設定 Referrer-Policy 標頭，以便傳送轉介網址

• 洽談外掛程式未呈現在 Firefox

  • 移除 Firefox Facebook 容器附加元件。
  • 關閉內容封鎖（點擊搜尋列中的灰色保護盾）可讓外掛程式呈現。

後續步驟

• 傳送回覆
• 傳送行銷訊息

另請參閱

• 停用常駐功能表
• Facebook JavaScript SDK
• 訪客模式 - 允許用戶在不登入 Facebook 的情況下開始對話。
• 破冰問題 - 允許用戶使用常見問題清單，與商家開始對話。
• 常駐功能表 - 協助用戶在整個對話過程中探索並更輕鬆地存取您的功能。