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

The plugin does not support:

Before You Start

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

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

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

Marketing Messages Opt In Requests

Visit our Marketing Messages guide for how to create marketing messages opt in requests.

Limitations

Only the Updates & Promotions topic is supported for Marketing Messages for Chat Plugin.

Messaging Optins Notification

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

Next Steps

• Send a reply
• Send Marketing Messages

See Also

• Disable Persistent Menu
• Facebook SDK for JavaScript
• 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.