洽談外掛程式(測試版)

洽談外掛程式可讓您將 Messenger 體驗直接整合在網站中。讓與您商家互動的顧客隨時能得到在 Messenger 中所提供的個人化、多媒體體驗。

洽談外掛程式會自動載入用戶與商家之間最近的對話記錄,包括用戶與商家在 messenger.com、Messenger 應用程式或網站的洽談外掛程式上最近的互動。這有助於為顧客打造單一體驗,即使顧客離開網頁後仍能持續對話。無需在後續追蹤時擷取顧客資訊,只需利用 Messenger 中的同一對話即可。

內容

功能支援

瀏覽器支援

洽談外掛程式支援現代熱門的桌上型電腦和行動瀏覽器(Messenger 應用程式內部瀏覽器和 Internet Explorer 除外)。

訊息類型和範本支援

洽談外掛程式目前支援下列訊息類型和結構化訊息範本:

功能 支援

文字訊息

影片/圖像/音訊/GIF

一般型/按鈕範本

是(支援的按鈕類型有限)

回傳

網址按鈕

通話按鈕

購買按鈕

分享按鈕

登入按鈕

登出按鈕

玩遊戲按鈕

清單/媒體/開放社交關係圖範本

快速回覆

是(支援的快速回覆類型有限)

文字快速回覆

用戶電話號碼快速回覆

用戶電子郵件快速回覆

地點快速回覆

常駐功能表

傳送者動作

納入 SDK

若要使用洽談外掛程式,您必須將包含顧客聊天 SDK 的 Facebook JavaScript SDK 版本包括在要顯示該外掛程式的網頁內。

如需有關將 SDK 包括在內的指示,請參閱顧客聊天 SDK

本地化和國際化

若要利用國際化(包括自動翻譯語言)的功能,您需要變更 SDK 的地區以符合您網站的地區。明確而言,您需要在起始 SDK 時,將 en_US 變更為支援的地區設定代碼。

如需更多資訊,請參閱社交外掛程式本地化和 JavaScript SDK

外掛程式的動態控制

我們也提供 API,來讓您動態地控制某些外掛程式的動作,例如開啟和關閉對話方塊。

如需詳細資訊,請參閱 顧客洽談 SDK

設定外掛程式

若要將洽談外掛程式置入網頁,您可以使用設定工具,或使用開發人員步驟來進行設定。

選項 1:使用設定工具

粉絲專頁設定也為粉絲專頁管理員提供一款簡單好用的設定工具,可讓您自訂洽談外掛程式。若要使用設定工具,請執行以下操作:

  1. 前往粉絲專頁設定 > 傳訊
  2. 在「新增 Messenger 到網站」區塊中,點擊「開始使用」按鈕。

這款安裝工具提供簡潔的用戶介面,供您自訂問候訊息、主題色彩、顯示的回覆時間,以及為外掛程式設定列入允許清單的網域。

完成設定後,設定工具會自動產生可複製/貼上的程式碼片段,讓您將洽談外掛程式置入網頁。

選項 2:使用開發人員的步驟進行設定

若要將洽談外掛程式置入網頁,請執行以下操作:

  1. 將網站的網域列入允許清單

    基於安全考量,只有在您已經列入允許清單的網域上載入這個外掛程式時,外掛程式才會顯示。請參閱 whitelisted_domains 參考資料,瞭解如何以程式設計方式將您的網域列入允許清單。

    網域名稱和 HTTPS 必要條件

    網域必須符合以下要求才能列入允許清單:

    • 透過 HTTPS 提供

    • 使用完整網域名稱,例如 https://www.messenger.com/。允許清單不支援 IP 位址和 localhost。

    如果企業的 Messenger 體驗是由服務供應商提供,因為企業本身並未擁有該 Facebook 應用程式,所以就無法存取應用程式設定中的粉絲專頁權杖產生器。在此情況下,您可透過「粉絲專頁設定」來新增或移除已列入允許清單的網域。若要將網域列入允許清單,請執行下列操作:

    1. 點擊粉絲專頁頂端的設定
    2. 點擊左側的 Messenger 平台
    3. 已列入允許清單的網域區塊中,編輯已列入粉絲專頁允許清單的網域
  2. 將外掛程式包括在網頁內

    若要在您的網頁中納入外掛程式,請在 HTML 中加入 div 和下列屬性:
    <div class="fb-customerchat"
     page_id="<PAGE_ID>">
    </div>

    根據預設,「問候」對話方塊會在桌面版和行動版上顯示。若要自訂「問候」對話方塊的行為,可以使用 greeting_dialog_display 和「greeting_dialog_delay」屬性。

    建議位置

    強烈建議您不要變更洽談外掛程式的預設位置,即網頁右下角。

    如需完整屬性清單,請參閱洽談外掛程式參考資料

  3. 選用。處理新對話的 messaging_postbacks 事件

    如果透過此外掛程式展開新對話,而且 Bot(機器人程式)已設定開始使用按鈕,當用戶點擊「開始使用」按鈕時,我們會向 Webhook 傳送 messaging_postbacks Webhook 事件

    如果您在洽談外掛程式中設定 ref 屬性,回傳事件中就會包含該屬性。

    重大變更(2020 年 5 月 5 日)

    洽談外掛程式的圖形 API 7.0 以上版本 messaging_postback Webhook 事件將不會傳回 sender.id 欄位。以上指令會傳回新的 sender.user_ref 欄位。此變更將從 2020 年 11 月 2 日起對所有舊版的圖形 API 版本生效。

    新版訊息回傳 Webhook 事件(圖形 API 7.0 以上版本,以及從 2020 年 11 月 2 日開始的所有圖形 API 版本)

    {
      "sender":{
        "user_ref":"<USER_REF>" // new field
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    舊版訊息回傳 Webhook 事件(圖形 API 6.0 以下版本,支援至 2020 年 11 月 2 日)

    {
      "sender":{
        "id":"<PSID>"
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    透過新的 messaging_postback Webhook 格式,您將使用 USER_REF 傳送訊息。USER_REF 將不適用於用戶個人檔案 API。當用戶回覆時,您將取得 PSID,並可將其用於傳送 API 和用戶個人檔案 API。

    使用 USER_REF 傳送 API

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    
  4. 選用。處理現有對話的 messaging_referrals 事件

    對於既有對話,如果您在洽談外掛程式中設定 ref 屬性,當該對話透過外掛程式繼續時,messaging_referrals Webhook 事件就會傳送到 Webhook。

    ref 可以是任何字串,並且可用於各種目的。例如,您可用來追蹤哪些顧客透過外掛程式與企業互動。

    重大變更(2020 年 5 月 5 日)

    洽談外掛程式的圖形 API 7.0 以上版本 messaging_referrals Webhook 事件將不會傳回 sender.id 欄位。以上指令會傳回新的 sender.user_ref 欄位。此變更將從 2020 年 11 月 2 日起對所有舊版的圖形 API 版本生效。

    新版轉介 Webhook 事件(圖形 API 7.0 以上版本,以及從 2020 年 11 月 2 日開始的所有圖形 API 版本)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "user_ref":"<USER_REF>" // new field
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    舊版轉介 Webhook 事件(圖形 API 6.0 以下版本,支援至 2020 年 11 月 2 日)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "id": "<USER_PSID>"
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    透過新的 messaging_referrals Webhook 格式,您將使用 USER_REF 傳送訊息。USER_REF 將不適用於用戶個人檔案 API。當用戶回覆時,您將取得 PSID,並可將其用於傳送 API 和用戶個人檔案 API。

    使用 USER_REF 傳送 API

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

自訂外掛程式

洽談外掛程式支援下列自訂項目。若您的網頁已加入外掛程式,您必須以屬性形式設定所有自訂項目:

屬性 說明

theme_color

選用。外掛程式的主題顏色,包括洽談外掛程式圖示的背景顏色,以及用戶傳送的訊息背景顏色。支援任何具有前置井字號的十六進位值色碼(例如 #0084FF),白色除外。強烈建議您選擇與白色呈現高對比的顏色。

logged_in_greeting

選用。若用戶已登入 Facebook,系統便會顯示這段問候語。最多可輸入 80 個字元。

logged_out_greeting

選用。若用戶未登入 Facebook,系統便會顯示這段問候語。最多可輸入 80 個字元。

greeting_dialog_display

選用。設定「問候」對話方塊顯示方式。支援下列值:


  • show:在經過 greeting_dialog_delay 屬性所設定的秒數之後,會在桌面版和行動版上顯示「問候」對話方塊,並持續開啟此方塊。
  • hide:在用戶於桌面版和行動版上點擊外掛程式之前,一律隱藏「問候」對話方塊。
  • fade:在經過 greeting_dialog_delay 屬性所設定的秒數之後,「問候」對話方塊會在桌面版上短暫顯示,然後就慢慢消失並隱藏。

外掛程式設定在桌面版和行動版上預設為 show。如需詳細資訊,請參閱下方變更行為一節。

greeting_dialog_delay

選用。設定載入外掛程式後到顯示「問候」對話方塊前的延遲秒數,可用來自訂顯示「問候」對話方塊的時間點。如果已設定 greeting_dialog_delay,但未設定 greeting_dialog_display,我們仍會在桌上型電腦上延遲顯示「問候」對話方塊,但不會將延遲套用到行動裝置。

ref

選用。如果想要在 Webhook 事件中傳回其他相關內容,您可以傳遞選用的 ref 參數。這可以有許多用途,例如追蹤用戶開始對話的頁面、將用戶導向至 Bot 中所提供的特定內容或功能,或是將 Messenger 用戶連結到網站上的連線階段或帳號。

停用常駐功能表

在某些情況下,我們會建議您停用洽談外掛程式中 Bot(機器人程式)的常駐功能表。若要這麼做,請在設定常駐功能表時,新增 "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"]

範例:Messenger 個人檔案 API 承載

{
  "persistent_menu":[
    {
      "locale":"default",
      "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
      "composer_input_disabled": false,      
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]
    }
  ]
}

訪客模式

部分商家頁面能夠存取洽談外掛程式的「訪客模式」,讓用戶無需登入 Facebook 帳號即可透過洽談外掛程式開始與商家聊天。這些「訪客用戶」是臨時帳號,當用戶在您的網站上時可接收訊息。若用戶決定從「更多」功能表結束對話,或從對話開始後 24 小時結束聊天(無論何者為先),「訪客聊天」將會結束。訪客名稱會顯示為「訪客」,後面接著簡短的數字字串。

如果商家嘗試在訪客帳號已終止時向該訪客用戶傳送訊息,將會看到錯誤訊息「這位用戶無法接收訊息:這位用戶現在無法接收您的訊息。」這些「訪客聊天」文字記錄將在訪客用戶的瀏覽器中保留長達 24 小時。不過,即使聊天過期,商家也會在收件匣中保留對話/文字記錄的副本,直到將其刪除。

從 6 月 16 日開始,開發人員(其粉絲專頁可存取「訪客模式」)將在外掛程式實作方式中看到下列變更:

  • 收發訊息轉介 Webhook:我們已經讓識別訪客用戶更容易。messaging_referrals Webhook 將包含一個 is_guest_user=true 標示來指出訪客用戶。
  • 終止 Webhook:當訪客用戶選擇結束對話時,我們將傳送 Webhook 通知,讓商家知道該訪客已不存在。後續訊息將無法傳送到該 GuestID。

商家可對訪客模式進行以下控制:

  • 前往「粉絲專頁設定」→「訊息」→「將 Messenger 新增到您的網站」→「立即開始」→「關閉訪客模式」,開啟/關閉訪客模式
  • 在 Facebook 的粉絲專頁收件匣中封鎖訪客用戶
  • 提交此表單來檢舉屢犯的訪客用戶

收發訊息轉介 Webhook

訪客用戶的 messaging_referrals Webhook 現已包括 is_guest_user=true 標示,用來指示此為訪客用戶的 Webhook。

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>",
     "is_guest_user": "true"
  }
}

終止 Webhook

當訪客用戶結束洽談外掛程式上的對話時,我們將傳送 Webhook 通知,讓開發人員知道 GUEST_ID 已失效且不再接收訊息。開發人員應確認其環境可防止收到此對話的後續訊息。

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "END_CHAT",
     "referer_uri": "<WEBSITE_URL>"
     "is_guest_user": "true" #this is optional
  }
}

用戶個人檔案 API

地區設定、性別和時區資訊不適用於訪客用戶。

curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,is_guest_user"
  
{
    "first_name": "Guest",
    "last_name": "1234",
    "profile_pic": "https://example.com/profile.jpg",
    "is_guest_user": "true"
}

對話 API

對話 API user_id 參數也將接受 GUEST_ID,以允許開發人員取得訪客用戶的對話串歷史記錄。

curl -i -X GET \
 "https://graph.facebook.com/v7.0/me/conversations?user_id=<PSID/GUEST_ID>"

傳送 API

傳送 API id 參數也將接受 GUEST_ID,以允許開發人員向訪客用戶傳送訊息。

curl -X POST -H "Content-Type: application/json" -d '{
  "messaging_type": "<MESSAGING_TYPE>",
  "recipient": {
    "id": "<GUEST_ID>"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

用戶登入

如果用戶已登入 Facebook 帳號,將能夠與 Bot(機器人程式)立即開始聊天。如果用戶尚未登入,則會顯示預設的歡迎訊息,並提示用戶登入或建立新的 Facebook 帳號。

使用年齡/國家/地區限制的粉絲專頁

如果您的粉絲專頁在「粉絲專頁」設定中已設定年齡或國家/地區限制,當用戶瀏覽您的網站時,若未登入其 Facebook 帳號,將不會顯示洽談外掛程式。

快取行為

此問候對話方塊狀態會儲存於瀏覽器的快取中,即使關閉和重新開啟瀏覽器也會持續存在。根據瀏覽器快取,外掛程式將一律預設為用戶離開外掛程式時的最後狀態(Safari 12 以上版本和 Firefox 瀏覽器除外)。

根據每個新外掛程式要求的預設,問候對話方塊會在桌面版和行動版上顯示。用戶可以點擊關閉按鈕以最小化對話方塊,或者您可以使用自己的顯示偏好設定來覆寫要求的預設。

偵測訊息原始來源

有時可能需要判斷用戶是否使用洽談外掛程式來與您的商家互動。為了啟用這項功能,Messenger 平台會針對所有從外掛程式傳送的訊息,在訊息承載中加入 "source": "customer_chat_plugin" 屬性

範例:訊息 Webhook 事件

{
    "object": "page",
    "entry": [
        {
            "id": "<PAGE_ID>",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "<USER_PSID>"
                    },
                    "recipient": {
                        "id": "<PAGE_ID>"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

Wordpress 外掛程式

為了讓您更輕鬆將洽談外掛程式整合至 Wordpress 網站,我們在 wordpress.org 上提供官方版的 Messenger 顧客洽談 Wordpress 外掛程式。

疑難排解提示

如果無法正確顯示這個外掛程式,請嘗試以下提示:

  • 如果發生如「拒絕在框架中顯示 ***,因為上階項目違反下列內容安全性政策指示詞:***」等主控台錯誤,請檢查要顯示外掛程式的粉絲專頁網域是否已加入允許清單。此外,也請確認您並未將 Referrer-Policy 標題設定為 no-referrer
  • Firefox Facebook 容器附加元件可防止外掛程式出現。如果要讓外掛程式出現,請移除附加元件。
  • 在預設情況下,Firefox 桌面專用瀏覽器(第 63 版及以上版本)和 Firefox 行動瀏覽器會封鎖內容追蹤,進而防止外掛程式出現。關閉內容封鎖(點擊搜尋列中的灰色保護盾)可讓外掛程式出現。