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 the following:

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

Limitations

The following are not supported:

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

Before You Start

You will need:

  • A Facebook Page for your website linked to the Meta Business Suite
  • The pages_messaging permission
  • A Page access token requested from a person who can perform the MODERATE task on the Facebook Page

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

Set Up the Chat Plugin

To include the Chat Plugin on your website, you can use the Meta Business Suite or implement the plugin programmatically.

Use the Meta Business Suite (Recommended)

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:

  • Standard - Get the code to add the plugin to your website. This includes the Facebook SDK for JavaScript implementation code.
  • Wordpress - Add the plugin to your Wordpress homepage.
  • Google Tag Manager - Add the plugin using the Google Tag Manager.

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.

Use the API

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.

Example Request

Formatted for readability.
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"

Webhooks

New Conversations

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.

Messaging Postback Webhook Event

{
  "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 Profile API will not work on USER_REF.
  • You will get PSID when the user replies and can then used it for future Graph API calls.
  • Webhooks that contains PSID (echo, delivery, read receipt, etc) will not be delivered for USER_REF based messages.

Send API with USER_REF

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

Existing Conversations

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.

Referral Webhook Event

{
    "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.

Send API with USER_REF

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

Detect Message Origin

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

Example Messages Webhook Event

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

Log In a User

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.

Pages Using Age/Country Restrictions

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.

Caching Behavior

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.

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

  • Customize Your Plugin
  • Guest Mode - Allow users to start conversations without being logged in to Facebook.
  • Ice Breakers - Allow users to start a conversation with a business with a list of frequently asked questions.
  • Persistent Menu - Help people discover and more easily access your functionality throughout the conversation.