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 the following:
|
|
|
The following are not supported:
|
|
You will need:
pages_messaging
permissionMODERATE
task on the Facebook PageThe Meta Business Tools Terms apply in connection with your usage of the Chat Plugin.
To include the Chat Plugin on your website, you can use the Meta Business Suite or implement the plugin programmatically.
Step 1.Navigate to the Meta Business Suite.
Step 2. Select your business' Facebook Page in the dropdown menu in the left side navigation menu. You may need to hover over the menu to expand the full menu.
Step 3. Select Inbox in the left side navigation menu.
Step 4. Select the Chat Plugin tab above of the message window.
Step 5. Click the Set up button.
Step 6. Pick the setup method and follow the instructions:
You can also use the Meta Business Suite to customize an automated welcome message to help start converstations and to customize your Chat Plugin to complement your brand.
Step 1. 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> <!-- Your Chat Plugin code --> <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> <!-- Your SDK code --> <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>
Step 2. Whitelist the domain of your website using the Messenger Profile API or the Meta Business Suite.
Step 3. Customize your Chat Plugin
Send a POST
request to the /PAGE-ID/chat_plugin
endpoint to customize the welcome screen greeting, color, icon, and more, for your plugin.
curl -i -X POST "https://graph.facebook.com/v14.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"
If 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 when the user clicks the "Continue as [NAME]" or "Continue as Guest" button.
If you are sending any automated welcome message when receiving the messaging_postbacks
webhook event, you will need to make some adjustment to send the message using user_ref
field instead of PSID
.
If the ref
attribute is set in the include for the Chat Plugin, it will be included in the postback event. Only alphanumeric characters as well as -, _, and = are supported.
{ "sender":{ "user_ref":"<USER_REF>" }, "recipient":{ "id":"<PAGE_ID>" }, "timestamp":1458692752478, "postback":{ "title": "<TITLE_FOR_THE_CTA>", "payload": "<USER_DEFINED_PAYLOAD>", "referral": { "ref": "<USER_DEFINED_REFERRAL_PARAM>", "source": "CUSTOMER_CHAT_PLUGIN", "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/v14.0
/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
For 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.
{ "object": "page", "entry": [ { "id": "<PAGE_ID>", "time": 1559598385735, "messaging": [ { "recipient": { "id": "<PAGE_ID>" }, "timestamp": 1559598385735, "sender": { "user_ref":"<USER_REF>" }, "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/v14.0
/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
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!"
}
}
]
}
]
}
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.
Referrer-Policy
header is set so that the referrer URL is sent