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 that you have read the Messenger Platform Overview and implemented the needed components for sending messages and receiving messages and notifications.
You will need:
pages_messaging
permissionMODERATE
task on your Facebook Pagemessaging
, messaging_postbacks
, and messaging_referrals
webhooks fieldsThe 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/ 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"
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.
theme_color
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.
logged_in_greeting
Optional. The greeting text that will be displayed if the user is currently logged in to Facebook. Maximum 80 characters.
logged_out_greeting
Optional. The greeting text that will be displayed if the user is currently not logged in to Facebook. Maximum 80 characters.
greeting_dialog_display
Optional. Sets how the plugin and greeting dialog will be displayed. The following values are supported:
show
: The greeting dialog is shown and remains open on desktop and mobile after the number of seconds set by the greeting_dialog_delay
attribute.fade
: The greeting dialog is shown briefly after the number of seconds set by the greeting_dialog_delay
attribute, then fades away and is hidden on desktop.hide
: The greeting dialog is hidden until a user clicks on the plugin on desktop and mobile. Greeting text will be shown beside the icon.icon
: The greeting dialog is hidden until a user clicks on the plugin on desktop and mobile. Greeting text will not be shown.The plugin setting defaults to show
on desktop and mobile.
See the Caching Behavior
section below for more.
greeting_dialog_delay
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 greeting_dialog_delay
is set but greeting_dialog_display
is not set, we will still delay the greeting dialog on desktop, however we will not honor the delay on mobile.
ref
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 & Promotionstopic 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