Customer Chat Plugin (beta)

The Messenger Platform's customer 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 customer 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 customer 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.

Contents

Feature Support

Browser Support

The customer chat plugin is supported for desktop and mobile with the following exceptions where it is not supported:

  • Internet Explorer
  • Messenger in-app browsers

Message Type & Template Support

Currently, the customer chat plugin supports the follow message types and structured message templates:

Feature Supported

Text Message

Yes

Video/Image/Audio/GIF

Yes (Receive Only)

Generic/Button Template

Yes (Supported for limited button types)

Postback

URL Button

Call Button

Buy Button

Share Button

Log In Button

Log Out Button

Game Play Button

List/Media/Open Graph Template

No

Quick Replies

Yes (Supported for limited quick reply types)

Text Quick Reply

Location Quick Reply

Persistent Menu

No

Localization

For localization of the plugin, see Localization with Social Plugins and JavaScript SDK.

Caching Behavior

By default, the plugin will be shown on desktop and minimized on mobile. Users can also click to show or minimize the plugin. This state is cached on the browser for the duration of the page session (including page reloads).

Requirements

To use the customer chat plugin, you must include the Facebook JavaScript SDK in the page where the plugin will be rendered. Please note that the customer chat plugin will not render in the webview inside any Messenger or Facebook app.

For instructions on including the SDK, see Facebook JavaScript SDK Quickstart.

Setup Steps

To include the customer chat plugin on your webpage, do the following:

  1. Whitelist the domain of your website

    Domain Name and HTTPS Required

    Domains must meet the following requirements to be whitelisted:

    • Served over HTTPS

    • Use a fully qualified domain name, such as https://www.messenger.com/. IP addresses and localhost are not supported for whitelisting.

    For security reasons, the plugin will only render when loaded on a domain that you have whitelisted. Refer to whitelisted_domains reference to learn how to whitelist your domain.

    Businesses whose Messenger experience is provided by a service provider, will not have access to the page token generator in app settings because they do not own the Facebook app. In this case, you may add or remove whitelisted domains via Page settings. To whitelist a domain, do the following:

    1. Click Settings at the top of your Page
    2. Click Messenger Platform on the left
    3. Edit whitelisted domains for your page in the Whitelisted Domains section
  2. Include the plugin on your webpage

    Recommended Positioning

    We highly suggest not changing the default position of the customer chat plugin from the bottom-right corner of your page.

    To add the plugin to your webpage, include a div with the following attributes in your HTML:
    <div class="fb-customerchat"
     page_id="<PAGE_ID>"
     ref="<OPTIONAL_WEBHOOK_PARAM>"
     minimized="<true|false>">
    </div>

    By default, the plugin will be shown on desktop and minimized on mobile. To customize this behavior, specify the optional minimized attribute.

    For a complete list of attributes, see the Customer Chat Plugin reference.

  3. Optional. Handle the messaging_postbacks event for 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 to your webhook when the user clicks the get started button.

    If the ref attribute is set in the include for the customer chat plugin, it will be included in the postback event.

  4. Optional. Handle the messaging_referrals event for existing conversations

    For existing conversations, if the ref attribute is set in the include for the customer 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.

User Login

Pages Using Country Restrictions

If your Page has country restrictions set in Page settings, the customer chat plugin will not render for users who are not logged into their Facebook account when they visit your website.

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.

Detecting Message Origin

At times, it may be necessary to determine whether a message was sent from the customer chat plugin. To enable this, the Messenger Platform will include a "source": "customer_chat_plugin" property in the tags array of the message payload for all messages sent from the plugin:

"message": {
  "mid":"mid.14577641449818:41d102a3e1ae206a38",
  "text":"hello, from customer chat!",
  "tags": [
    {
      "source": "customer_chat_plugin"
    }
  ]
}