Chat Plugin

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.

How It Works

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.

Logins

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.

Webhook Notifications

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:

  • Information about the person, such as Page-scoped IDs (PSID) or User-reference IDs
  • Identify the source of the message as Chat Plugin
  • Referral information included in the notification

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.

Existing Conversations

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.

Message Types supported by Chat Plugin

  • Audio, Video, Image, and GIFs
  • Call Buttons
  • Persistent Menu
  • Postback Buttons
  • Sender Actions
  • Text Messages
  • Text Quick Replies
  • URL Buttons
  • User Email Quick Replies
  • User Phone Number Quick Replies

The plugin does not support:

  • Buy Buttons
  • Game Play Buttons
  • List, Media, or Open Graph Templates
  • Location Quick Replies
  • Log In Buttons
  • Log Out Buttons
  • Messenger in-app browsers
  • Share Buttons

Before You Start

This guide assumes that you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.

You will need:

  • The pages_messaging permission
  • A Page access token requested from a person who can perform the MODERATE task on your Facebook Page
  • The app linked to your Facebook Page subscribed to the messaging, messaging_postbacks, and messaging_referrals webhooks fields
  • The domain for your website added to the allowlist using the Messenger Profile API or the Meta Business Suite

The Meta Business Tools Terms apply in connection with your usage of the Chat Plugin.

Limitations

  • Your website must be live or allowlisted before Chat Plugin can be successfully implemented
  • If your business' Facebook Page has age or country restrictions set in Page settings, the Chat Plugin will not render for people who are not logged into their Facebook account when they visit your website.
  • Greeting dialog is not cached for Safari 12+ and Firefox browsers

Add the Chat Plugin

Step 1. Add the SDK

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>

Step 2. Customize the Plugin

Use the API

Send a POST request to the /PAGE-ID/chat_plugin endpoint to customize the greeting, color, icon, and more, for your plugin.

Example Request

Formatted for readability.
curl -i -X POST "https://graph.facebook.com/v15.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.

Use HTML attributes

We recommend that you only use this method for customizations that are not available via Page settings setup tool or the API.

AttributeDescription

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.

Webhooks Notifications

When a person sends your business a message, a webhook notification will be sent to your server.

Existing Conversations

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.

Messaging Notification

{
    "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!"
                    }
                }
            ]
        }
    ]
}

Messaging Referrals Notification

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"
                    }
                }
            ]
        }
    ]
}

New Conversations

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.

Messaging Postbacks Notification

{
    "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",
                    }
                }
            ]
        }
    ]
}

Recurring Notification Opt In Requests

To set up recurring notification opt in requests for your Chat Plugin, please visit the Meta Business Help Center for more information.

Limitations

Only the Updates & Promotions topic is supported for Recurring Notifications for Chat Plugin.

Messaging Optins Notification

A messaging_optins webhook notification will be sent to your server when a person opts in to receiving recurring notifications 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 recurring notifications to a person.

Troubleshooting Tips

  • Refuse to display...
    • Make sure your domain has been whitelisted
    • Make sure the Referrer-Policy header is set so that the referrer URL is sent
  • Chat Plugin not rendering on Firefox
    • Remove the Firefox Facebook Container Add-On.
    • Turn off content blocking (click the gray shield in the search bar) to see the plugin render.

See Also