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:

Limitations

The following are not supported:

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

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

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

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

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.

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.