聊天插件

本文档展示如何通过编程方式将聊天插件添加到您的网站版 Messenger 体验中。

如果您想使用 Meta Business Suite 将聊天插件添加到您的网页（推荐做法），请访问 Meta Business 帮助中心，了解更多信息。

运作方式

在您的网页上安装 JavaScript 版 Facebook SDK 后，该网页便会显示聊天插件。桌面端和移动端将默认显示问候对话框，用户可点击关闭按钮将此框最小化。您可以自定义此插件的问候语、外观（如颜色）和消息体验（如菜单和快速回复）。无论问候对话框的状态是最大化还是最小化，系统都会予以缓存，即使切换会话，该状态也会保持不变。

登录

如果用户已登录 Facebook，则聊天插件会显示“以 [姓名] 的身份继续”和“以访客身份继续”按钮。如果用户未登录 Facebook，则该插件将显示“登录 Messenger”和“以访客身份继续”按钮。

Webhooks 通知

用户点击聊天插件发起或继续与您商家的聊天时，系统会向您的服务器发送 Webhooks 通知，其中包含以下内容：

• 与此用户相关的信息，如公共主页范围编号 (PSID) 或用户参考编号
• 将消息来源标记为聊天插件
• 已包含在通知中的推荐信息

如果您在聊天插件中实现了欢迎画面 ，当用户点击“开始”按钮发起与您商家的对话，系统会向您的服务器发送 messaging_postbacks Webhooks 通知。之后，您的商家便可以使用用户参考编号在 24 小时标准消息时间范围内向该用户发送消息。

已有对话

如果此用户与您的商家间已有对话，则聊天插件会自动加载相关聊天记录。当用户通过发送消息、点击按钮或采取您已在对话中实现的某个其他操作来继续对话时，系统会向您的服务器发送 messaging Webhooks 通知；如果您在通知中加入了推荐信息，则在此情况下系统会发送 messaging_referral Webhooks 通知。之后，您的商家便可使用 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

为要显示插件的每个网页添加 JavaScript 版 Facebook 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/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 通知

当用户向您的商家发送消息时，系统便会向您的服务器发送 Webhooks 通知。

已有对话

如果用户与您的商家间已有对话，当该用户在此类对话中发送消息时，系统便会发送 messaging Webhooks 通知。通知内容将包括该用户的公共主页范围编号和 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 Webhooks 通知。

{
    "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 Webhooks 通知。

消息回传通知

{
    "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 Webhooks 通知。

"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 容器附加组件。
  • 只需关闭内容拦截功能（点击搜索栏中的灰色盾牌图标），此插件便会出现。

后续步骤

• 发送回复
• 发送营销消息

另请参阅

• 停用固定菜单
• JavaScript 版 Facebook SDK
• 访客模式 - 允许用户在未登录 Facebook 的情况下发起对话。
• 破冰活动 - 允许用户通过常见问题清单与公司发起对话。
• 固定菜单 - 帮助用户在整个对话过程中发现各功能并轻松访问。