Messenger Platform


Checkbox Plug-in

When your Facebook app is in Development Mode, plugin and API functionality will only work for admins, developers and testers of the app that have a valid session. After your app is approved and public, it will work for the general public.

The Checkbox Plugin allows you to authenticate people with Messenger and start a thread using your website. It's similar to the "Send to Messenger" plugin, but optimized for forms where you want to provide a seamless way for people to receive updates via Messenger.

It could be used for just about any form-based flow on a site, including ecommerce websites where you wish to send receipts and order updates to the user, for event RSVPs, or even signup forms.

  1. How it Works
  2. Implementation
  3. Troubleshooting Tips


To use the checkbox plug-in, you must include the Facebook for Javascript SDK in the page where the plug-in will be rendered.

For instructions on including the SDK, see the Facebook for Javascript SDK Quick Start.

How It Works

The Checkbox Plugin enables you to integrate authentication into a user flow on your website. It has a checkbox that fits naturally with existing forms.

When a person is logged into Facebook in their browser, their session will be detected and their name and profile picture will be shown beneath the checkbox. This lets the user know which identity will be opted into communication with the business if they proceed.

If the identity displayed isn't the person using the site, they can click the "Not you?" link to log out. It will clear the active Facebook session and present a login dialog.

Customizing Default State

While historically it was possible to customize the default state of the checkbox plug-in, beginning October 6, 2017, the default state of the checkbox plug-in will be unchecked only. Websites that implemented the plug-in before this date will still be able to select checked as the default state.

The default state can be set at render-time to make it either an opt-in or opt-out experience.

Customizing Login Behavior

If there is no logged in Facebook user, the plugin will be rendered without a user identity displayed. Clicking in the checkbox will prompt the user to log in.

If you set allow_login to false, then the plugin will not render for users who are not logged in. For users with an active Facebook session, the plugin will render without the 'Not you?' link.

Note that the plugin will render without a Facebook session only if the app is approved and public.


The Facebook JavaScript SDK is required to render the Checkbox plugin. Subscribe to an event to get the state of the checkbox. Confirm the opt-in by triggering a client-side event using a Facebook App Event.

The web plugin takes a user_ref parameter which is used as an identifier for the user. When the user finishes the flow, we will pass this identifier back to you to identify the user. This parameter should be unique not just for every user, but for every time the plugin is rendered. If the parameter is not unique, then the plugin may not render.

Whitelist your domain

For security reasons, the plugin will render only when loaded on a domain that you have whitelisted. Refer to this reference doc to learn how to whitelist your domain. Once you have whitelisted the domain, you can set it as value for the plugin origin parameter.

Render the Plugin

Add the plugin to your page by loading the Facebook JavaScript SDK and adding a div with the attributes below.

<div class="fb-messenger-checkbox"  
  prechecked="<true | false>
  size="<small | medium | large | standard | xlarge>">

For a complete description of available attributes, see the checkbox plug-in reference.

Check the state of the checkbox

You can subscribe to client-side events to check the state of the checkbox.

  window.fbAsyncInit = function() {
      appId      : '197650983945848',
      xfbml      : true,
      version    : 'v2.6'

    FB.Event.subscribe('messenger_checkbox', function(e) {
      console.log("messenger_checkbox event");
      if (e.event == 'rendered') {
        console.log("Plugin was rendered");
      } else if (e.event == 'checkbox') {
        var checkboxState = e.state;
        console.log("Checkbox state: " + checkboxState);
      } else if (e.event == 'not_you') {
        console.log("User clicked 'not you'");
      } else if (e.event == 'hidden') {
        console.log("Plugin was hidden");

Confirming Opt-in

When the form is about to be submitted, or when the flow is otherwise done, you must send a MessengerCheckboxUserConfirmation event. It is not required to verify the state of the checkbox before doing so.

The sample code below uses the AppEvents function to call to confirm the opt-in.

You may pass an optional ref parameter if you wish to include additional context to be passed back in the webhook event. It has the same behavior as for the Send To Messenger plugin (as distinct from user_ref).

        function confirmOptIn() {
          FB.AppEvents.logEvent('MessengerCheckboxUserConfirmation', null, {

    <input type="button" onclick="confirmOptIn()" value="Confirm Opt-in"/>



After the opt-in event, we will post a webhook event to your server if the checkbox state was checked. This callback has the same format as the opt-in callback, but instead of a sender field, it has an optin object with a user_ref field.


Calling the Send API

After you receive the callback event, you can call the Send API to start messaging the user using the user_ref identifier in recipient as shown below. Note that this field is the same as the unique user_ref param used before when the plugin was rendered and in confirming the opt-in.

If the call to the Send API is successful, the response will contain a recipient_id parameter, which is a stable user ID that you can now use in future API calls.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
  "message": {
    "text":"hello, world!"
}' "" 

Troubleshooting Tips

If you're having trouble getting the plugin to properly render, try the tips below:

  1. Verify that your bot is actually approved for the pages_messaging permission.
  2. Verify that your page has webhook subscription to your bot.
  3. If you see a console error like "Refused to display *** in a frame because an ancestor violates the following Content Security Policy directive: ***", check that the domain of the page the plugin is being rendered on has been whitelisted.
  4. If the allow_login parameter is set to false, you will need to have a valid Facebook user session (i.e. not logged in as a page) otherwise the plugin will be hidden.
  5. Testing on localhost is not supported right now.