洽談附加程式

本文件將為您展示如何透過程式輔助的方式，將洽談附加程式加入您網站上的 Messenger 體驗。

若您希望使用 Meta Business Suite 將洽談附加程式加入您的網頁（推薦做法），請瀏覽 Meta 企業商家幫助中心了解詳情。

運作方式

當您在網頁上安裝 Facebook JavaScript SDK 後，洽談附加程式便會在網頁上顯示出來。在預設情況下，桌面電腦及流動裝置均會顯示打招呼對話框，用戶可以點擊關閉按鈕，將該對話框縮到最小。您可以自訂附加程式的打招呼訊息、外觀（如顏色）和訊息體驗（如選單和快速回覆）。系統會快取對話框的狀態、將對話框放到最大或縮到最小，並在不同的連線階段之間保持相同狀態。

登入

如果用戶已登入 Facebook，附加程式會顯示「以 [NAME] 的身分繼續」和「以訪客身分繼續」按鈕。如果用戶未登入 Facebook，附加程式則會顯示「登入 Messenger」和「以訪客身分繼續」按鈕。

Webhooks 通知

當用戶點擊附加程式來開始或繼續與您的企業聊天時，系統會向您的伺服器傳送一則 Webhook 通知，其中包含：

• 有關此用戶的資訊，例如專頁專屬編號（PSID）或用戶參考編號
• 將訊息來源識別為洽談附加程式
• 通知中包含的轉介資訊

如果您已在附加程式中設置歡迎畫面 ，當用戶點擊「開始對話」按鈕以與您的企業開始對話，系統就會傳送 messaging_postbacks Webhook 通知至您的伺服器。您的企業隨後可以使用用戶參考編號，在標準 24 小時訊息期間內向此用戶傳送訊息。

現有對話

如果用戶已與您的企業展開對話，聊天記錄將會自動載入附加程式中。當用戶繼續對話時，不論是傳送訊息、點擊按鈕還是執行您在對話中實施的其他動作，messaging Webhook 通知都會傳送至您的伺服器。或者，如果您希望在對話中加入轉介資訊，則系統會傳送 messaging_referral Webhook 通知。您的企業隨後可以使用 PSID，在標準 24 小時訊息期間內向此用戶傳送訊息。

洽談附加程式支援的訊息類型

此附加程式不支援下列項目：

準備工作

您需要準備以下事項：

• pages_messaging 權限
• 專頁存取憑證，由可以在您的 Facebook 專頁上執行 MODERATE 任務的用戶所要求
• 連結至 Facebook 專頁的應用程式，且專頁已訂閱 messaging、messaging_postbacks 和 messaging_referrals Webhooks 欄位
• 使用 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

向 /PAGE-ID/chat_plugin 端點傳送 POST 要求，以便為附加程式自訂打招呼訊息、顏色、圖示等。

要求範例

curl -i -X POST "https://graph.facebook.com/v20.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 的情況下展開對話。
• 開場白：允許用戶透過常見問題清單與企業展開對話。
• 常駐選單：協助用戶在整個對話過程中探索並更輕鬆地使用您的功能。