On May 9, 2024, you will no longer be able to access any of the functionality of the Chat Plugin. Effective immediately, Chat Plugin in guest mode is no longer available. Other features like m.me links will still be available for you to use.
This document shows you how to programmatically add the Chat Plugin to your Messenger experience on website.
If you would like to use the Meta Business Suite to add the Chat Plugin to your webpage (recommended), please visit the Meta Business Help Center for more information.
When you install the Facebook SDK for JavaScript on your webpage, the Chat Plugin will be rendered on the webpage. By default, the greeting dialog will be shown on desktop and mobile and a person may click the close button to minimize the dialog. You can customize the greeting, look, such as the color, and messaging experience, such as menus and quick replies, of the plugin. The state of the dialog is cached, maximized or minimized, and persists from session to session.
If the person is logged in to Facebook, the plugin will show the "Continue as [NAME]" and "Continue as Guest" buttons. If the person is not logged in to Facebook, the plugin will show the "Log into Messenger" and "Continue as Guest" buttons.
When a person clicks on the plugin to start or continue a chat with your business, a webhook notification will be sent to your server that contains:
If you have implemented the
Welcome Screen
in the plugin and the person clicks the Get Started button to start a conversation with your business, a messaging_postbacks
webhook notification will be sent to your server. Your business can then use the user reference ID to send messages to the person within the 24-hour standard messaging window.
If the person has an existing conversation with your business, the chat history will automatically load in the plugin. When the person continues the conversation, either sends a message, clicks a button, or takes some other action you have implemented in the conversation, a messaging
webhook notification will be sent to your server or a messaging_referral
webhook notification if you include referral information. Your business can then use the PSID to send messages to the person within the 24-hour standard messaging window.
|
|
|
The plugin does not support:
|
|
|
This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.
You will need:
pages_messaging
permission
MODERATE
task on your Facebook Page
messaging
, messaging_postbacks
, and messaging_referrals
webhooks fields
The Meta Business Tools Terms apply in connection with your usage of the Chat Plugin.
Add the Facebook SDK for JavaScript to each page of your website where you want to render the plugin.
<!-- 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>
Send a POST
request to the /PAGE-ID/chat_plugin
endpoint to customize the greeting, color, icon, and more, for your plugin.
curl -i -X POST "https://graph.facebook.com/v21.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"
Visit the Chat Plugin Reference for more information on fields used to customize your plugin.
We recommend that you only use this method for customizations that are not available via Page settings setup tool or the API.
Attribute | Description |
---|---|
| Optional. The color to use as a theme for the plugin, including the background color of the Chat Plugin icon and the background color of any messages sent by users. Supports any hexadecimal color code with a leading number sign (e.g. #0084FF), except white. We highly recommend you choose a color that has a high contrast to white. |
| Optional. The greeting text that will be displayed if the user is currently logged in to Facebook. Maximum 80 characters. |
| Optional. The greeting text that will be displayed if the user is currently not logged in to Facebook. Maximum 80 characters. |
| Optional. Sets how the plugin and greeting dialog will be displayed. The following values are supported:
The plugin setting defaults to |
| Optional.
Sets the number of seconds of delay before the greeting dialog is shown after the plugin is loaded. This can be used to customize when you want the greeting dialog to appear. If |
| Optional. You may pass an optional ref parameter if you wish to include additional context to be passed back in the webhook event. This can be used for many purposes, such as tracking which page the user started the conversation on, directing the user to specific content or features available within the bot, or tying a Messenger user to a session or account on the website. |
When a person sends your business a message, a webhook notification will be sent to your server.
A messaging
webhook notification is sent when a person sends a message to an existing conversation with your business. The notification will include the person's Page-scoped ID and the source
parameter of the tags
object set to 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!"
}
}
]
}
]
}
If you set the ref
attribute for your Chat Plugin, a messaging_referrals
webhook notification will be sent to your server.
{ "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" } } ] } ] }
A messaging_postbacks
webhook notification is sent when a person starts a conversation by clicking on the Get Started button in the Welcome Screen in the plugin.
{ "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", } } ] } ] }
Visit our Marketing Messages guide for how to create marketing messages opt in requests.
Only the Updates & Promotions topic is supported for Marketing Messages for Chat Plugin.
A messaging_optins
webhook notification will be sent to your server when a person opts in to receiving Marketing Messages from your business.
"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" } } ] } ] }
You can set the notification_messages_token
value to the ID value in the recipient
object to send Marketing Messages to a person.
Referrer-Policy
header is set so that the referrer URL is sent