The Facebook Business Tools Terms apply in connection with your usage of the Chat Plugin.
The Chat Plugin allows you to integrate your Messenger experience directly into your website. This allows your customers to interact with your business anytime with the same personalized, rich-media experience they get in Messenger.
The Chat Plugin automatically loads recent chat history between the person and your business, meaning recent interactions with your business on messenger.com, in the Messenger app, or in the Chat Plugin on your website will be visible. This helps create a single experience for your customers, and enables you to continue the conversation even after they have left your webpage. No need to capture their information to follow up, just use the same conversation in Messenger.
The Chat Plugin supports modern popular desktop and mobile browsers except Messenger in-app browsers and Internet Explorer.
Currently, the Chat Plugin supports the follow message types and structured message templates:
Feature | Supported |
---|---|
Text Message | Yes |
Video/Image/Audio/GIF | Yes |
Generic/Button Template | Yes (Supported for limited button types) Postback URL Button Call Button Buy Button Share Button Log In Button Log Out Button Game Play Button |
List/Media/Open Graph Template | No |
Quick Replies | Yes (Supported for limited quick reply types) Text Quick Reply User Phone Number Quick Reply User Email Quick Reply Location Quick Reply |
Persistent Menu | Yes |
Sender Actions | Yes |
To use the Chat Plugin, you must include a version of the Facebook JavaScript SDK that contains the Customer Chat SDK in the page where the plugin will be rendered.
For instructions on including the SDK, see Customer Chat SDK.
To take advantage of internationalization, including automatic language translation, you need to change the locale of the SDK to match the locale of your site. Specifically, you need to change en_US
to a supported locale code when initiating the SDK.
For more information, see Localization with Social Plugins and JavaScript SDK.
We also provide APIs that allow you to dynamically control certain behaviors of the plugin such as opening and closing the dialog.
For more information, see Customer Chat SDK.
To include the Chat Plugin on your webpage, you can either use the setup tool or setup using developer steps.
For Page Admins, the Page settings also provides an easy setup tool for customizing your Chat Plugin. To use the setup tool, do the following:
The setup tool provides a simple UI to customize various attributes of the Chat Plugin.
On completion, the setup tool automatically generates the code snippets that you can copy/paste to include the Chat Plugin in your webpage.
To include the Chat Plugin on your webpage, do the following:
For security reasons, the plugin will only render when loaded on a domain that you have whitelisted. Refer to whitelisted_domains
reference to learn how to whitelist your domain programmatically.
Domains must meet the following requirements to be whitelisted:
Served over HTTPS
Use a fully qualified domain name, such as https://www.messenger.com/. IP addresses and localhost are not supported for whitelisting.
Businesses whose Messenger experience is provided by a service provider, will not have access to the page token generator in app settings because they do not own the Facebook app. In this case, you may add or remove whitelisted domains via Page settings. To whitelist a domain, do the following:
div
with the following attributes in your HTML:
<div class="fb-customerchat"
page_id="<PAGE_ID>">
</div>
By default, the greeting dialog will be shown on desktop and mobile. To customize the greeting dialog behavior, you can use the greeting_dialog_display
and 'greeting_dialog_delay' attributes.
We highly suggest not changing the default position of the Chat Plugin from the bottom-right corner of your page.
For a complete list of attributes, see the Chat Plugin reference.
messaging_postbacks
event for new conversationsIf a new conversation is started via the plugin, and your bot has set up the get started button, we will send a messaging_postbacks
webhook event to your webhook when the user clicks the get started button.
If the ref
attribute is set in the include for the Chat Plugin, it will be included in the postback event.
Graph API v7.0+ messaging_postback
webhook event from the chat plugin will not be returning sender.id
field. It will return a new sender.user_ref
field. This changes will take effect on all older Graph API versions starting Nov 2, 2020.
{ "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", } } }
{ "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", } } }
With the new messaging_postback
webhook format, you will leverage USER_REF
to send messages. The following behavior applies for USER_REF
:
USER_REF
.PSID
when the user replies and can then used it for future Graph API calls.PSID
(echo, delivery, read receipt, etc) will not be delivered for USER_REF
based messages.
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/v10.0
/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
messaging_referrals
event for existing conversationsFor existing conversations, if the ref
attribute is set in the include for the Chat Plugin, a messaging_referrals
webhook event will be sent to your webhook when the conversation is continued via the plugin.
The ref
can be any string and can be used for a variety of purposes. For example, you could use it to keep track of which customers have engaged with your business via the plugin.
Graph API v7.0+ messaging_referrals
webhook event from the chat plugin will not be returning sender.id
field. It will return a new sender.user_ref
field. This changes will take effect on all older Graph API versions starting Nov 2, 2020.
{ "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>" } } ] } ] }
{ "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>" } } ] } ] }
With the new messaging_referrals
webhook format, you will leverage USER_REF
to send messages. USER_REF
will not work on User Profile API. You will get the PSID
when the user replies and can then use it on Send API and User Profile 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/v10.0
/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
The Chat Plugin supports the following customizations. There are several ways for developers to apply customization.
Most of the customizations (theme color, greeting, locale, guest mode, alignment and automatically expand) can be set directly via the plugin setup tool (FB page settings --> Messaging --> Add Messenger to your website --> Get Started).
The following customizations are currently supported:
We recommend that developers only use this method for customizations that are not available via Page settings setup tool.
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. |
There may be cases where it is preferable to disable the persistent menu for your bot in the Chat Plugin. To do this, add "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"]
when you set your persistent menu:
{
"persistent_menu":[
{
"locale":"default",
"disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
"composer_input_disabled": false,
"call_to_actions":[
{
"title":"My Account",
"type":"postback",
"payload":"PAYBILL_PAYLOAD"
}
]
}
]
}
Starting on August 4, 2020, people can start chatting with businesses via the Chat Plugin in guest mode without logging into their Facebook account. This allows businesses to seamlessly connect with more customers, regardless of their browser, device, or Facebook login status. These “guest users” are temporary accounts that can receive messages when the user is on your website. “Guest chats” will end when the user decides to end the chat from the More menu, or 24 hours from the start of the conversation, whichever comes first. The guest name will appear as “Guest” followed by a short numeric string.
If the business tries to send a message to this guest user when the guest accounts have been terminated, they will see an error message, “This Person Cannot Receive Messages: This person isn't receiving messages from you right now.” The transcript of these “guest chats” will remain on the guest user's browser for up to 24 hours. Businesses, however, will retain a copy of the conversation in their inbox even after the chat expires until they delete it.
The following changes in Plugin implementation will take effect as a result of this update:
messaging_referrals
webhook will include an is_guest_user=true
flag to indicate a guest user. We recommend that developers read this webhook and give businesses the option to treat guest users different from logged in users in designing their conversation flow. #100 No matching user found
will be sent. We recommend that developers read this webhook, notify the live agent and stop the conversation flow when a guest conversation is terminated.messaging_referrals
webhook from guest users now include the is_guest_user=true
flag, indicating this is a webhook from a guest user. Developer can refer to Handle the messaging_referrals event for existing conversations
section for instructions on how to setup referral webhooks.
{ "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" } }
When a guest user ends the conversation on the Chat Plugin, we will send a webhook to let developers know that the GUEST_ID
is no longer valid and will no longer be receiving messages. Developers should make sure their environment prevents future messages to this conversation.
{ "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 } }
Locale, gender and timezone information aren't available for guest users.
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" }
Conversation API user_id
parameter will also accept GUEST_ID
to allow developers to get the thread history of a guest user.
curl -i -X GET \ "https://graph.facebook.com/v7.0/me/conversations?user_id=<PSID/GUEST_ID>"
Send API id
parameter will also accept GUEST_ID
to allow developers to send messages to guest user.
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/v10.0
/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
Businesses experiencing issues with guest users have the following control:
Guest users will have the option to log in to Messenger to continue their chat with businesses. We call this the "upgrade" moment for the guest user.
A guest user can be prompted to log in to Facebook under three circumstances:
Pages that are not linked to any developer app will have guest upgrade feature available by default. Pages that are linked to a developer app will have the option to turn on guest upgrade via app dashboard under Messenger -> Settings -> Chat Plugin -> Guest Upgrade toggle. There are a couple of changes in the webhooks and API in order to support the "upgrade" moment.
There are a couple of changes in the webhooks and API in order to support the "upgrade" moment.
When a guest user upgrades, a new webhook with GUEST_UPGRADE
type will be sent to allow developers to know that the guest user has upgraded and the associated PSID
of the logged in user. Subsequent message webhooks after the guest user has upgraded will only contain PSID
.
{ "sender":{ "id": "<GUEST_ID>" }, "recipient":{ "id": "<PAGE_ID>" }, "timestamp": 1458692752478, "referral": { "ref": "<LOGGED_IN_USER_PSID>", "source": "CUSTOMER_CHAT_PLUGIN", "type": "GUEST_UPGRADE", "referer_uri": "<WEBSITE_URL>" } }
When a guest user upgrades, querying User Profile API with GUEST_ID
will return an additional psid
field to allow developers to associate/link GUEST_ID
with PSID
. The psid
field will return a PSID_EDGE
with the name and PSID
of the user by default.
curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,psid" { "first_name": "Guest", "last_name": "1234", "profile_pic": "https://example.com/profile.jpg", "psid": <PSID_EDGE> } <PSID_EDGE> { "name": "John Doe", "id": "<PSID>" }
With Conversation API now accepting GUEST_ID
there will be 3 different scenarios depending on the state of the guest user.
PSID
."data": [ { "id": "<logged_in_user_thread_id>", "link": "<link>", "updated_time": "<updated_time>" } ]
GUEST_ID
"data": [ { "id": "<guest_user_thread_id>", "link": "<link>", "updated_time": "<updated_time>" } ]
GUEST_ID
"data": [ { "id": "<guest_user_thread_id>", "link": "<link>", "updated_time": "<updated_time>" }, { "id": "<logged_in_user_thread_id>", "link": "<link>", "updated_time": "<updated_time>" } ]
If the user is already logged in to their Facebook account, they will be able to start chatting with your bot right away. If they are not logged in, a default welcome message will be display, and they will be prompted to log in or create a new Facebook account.
If your Page has age or country restrictions set in Page settings, the Chat Plugin will not render for users who are not logged into their Facebook account when they visit your website.
The greeting dialog state is cached on the browser and persists even when the browser is closed and reopened. The plugin will always default to the last state the user left the plugin based on the browser cache (with the exception of Safari 12+ and Firefox browsers).
By default for each new plugin request, the greeting dialog will be shown on desktop and mobile. Users may click the close button to minimize the dialog or you can override the request default with your own display preferences.
At times, it may be necessary to determine whether a user is engaging with your business using the Chat Plugin. To enable this, the Messenger Platform will include a "source": "customer_chat_plugin"
property inside the message payload for all messages sent from the plugin
{
"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!"
}
}
]
}
]
}
To make it easier to integrate the Chat Plugin into Wordpress sites, we offer the official Facebook Chat Plugin on wordpress.org.
If you're having trouble getting the plugin to render properly, try the tips below:
Referrer-Policy
header to no-referrer
.