Checkbox Plugin

The checkbox plugin allows you to display a checkbox in forms on your website that allows users to opt-in to receive messages from your bot in Messenger. If the person is currently logged in to Facebook, their profile photo and name will be displayed next to the checkbox. If the person is not logged in to Facebook or wants to log in as a different user, they can authenticate.

The checkbox plugin is similar to the Send to Messenger plugin, but is optimized for forms, and can be used for just about any form-based flow on your site. For example, you could include the plugin on an ecommerce website, where you wish to send receipts and order updates to the user.

Contents

• Requirements
• How it Works
• Best Practices & Usage Guidelines
• Implementation
• Customizing Default State
• Customizing Login Behavior
• Troubleshooting Tips

Requirements

To use the checkbox plugin, you must do the following:

• Include the Facebook for Javascript SDK in the page where the plugin will be rendered. For instructions on including the SDK, see the Facebook for Javascript SDK Quick Start.

• Ensure your usage of the plugin complies with local laws, including laws that require affirmative user action to opt in to promotional or direct marketing messages. Be aware that in many localities, a pre-checked box is not a valid opt-in action.

• Review and follow our best practices regarding usage and placement of the plugin.

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.

Best Practices & Usage Guidelines

To create the best user experience possible, it is important to ensure people visiting your website understand the purpose of the checkbox plugin and know they are using it to opt in to receive messages from you.

• Active opt-in: When a person opts-in to receive messages via the checkbox plugin, the opt-in must be triggered by a user action, such as a button press. Programmatically, you should trigger sending the MessengerCheckboxUserConfirmation event when the user takes this action.

• Checkbox placement: Place the checkbox plugin above the button that will send the MessengerCheckboxUserConfirmation event. Placing the plugin below the button can create confusion, and may result in the user not understanding they have opted-in, and as a result, reporting or blocking your bot. We have found that placement above the button results in a more intuitive understanding of the checkbox and its purpose.

• Clear opt-in messaging: Include text near the checkbox plugin that makes it clear it is an opt-in, and explains what type(s) of messaging (marketing, promotions, informational, etc.) the person is signing up for.

• Policy and community standards: Your use of the checkbox plugin, including the content you send once a person opts-in to receive messages with the plugin, must comply with all Messenger Platform policies and Facebook Community Standards. This includes ensuring your use of the plugin respects user privacy, and abides by all applicable local laws and regulations.

Implementation

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.

1. 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.

2. 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"  
  origin=<PAGE_DOMAIN>
  page_id=<PAGE_ID>
  messenger_app_id=<APP_ID>
  user_ref="<UNIQUE_REF_PARAM>"
  prechecked="<true | false>"
  allow_login="<true>"
  size="<small | medium | large | standard | xlarge>"
  skin="<light|dark>"
  center_align="<true|false>">
</div>

For a complete description of available attributes, see the checkbox plugin reference.

3. Check the state of the checkbox

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

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

    FB.Event.subscribe('messenger_checkbox', function(e) {
      console.log("messenger_checkbox event");
      console.log(e);
      
      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");
      }
      
    });
  }; 

4. Confirm opt-in

When the form is 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).

<html>
  <head>
    <script>
        function confirmOptIn() {
          FB.AppEvents.logEvent('MessengerCheckboxUserConfirmation', null, {
            'app_id':'<APP_ID>',
            'page_id':'<PAGE_ID>',
            'ref':'<PASS_THROUGH_PARAM>',
            'user_ref':'<UNIQUE_REF_PARAM>'
          });
      }
    </script>
  </head>

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

</html>        

5. Handle the messaging_optins webhook event

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.

{
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":<UNIX_TIMESTAMP>,
  "optin":{
    "ref":"<PASS_THROUGH_PARAM>",
    "user_ref":"<UNIQUE_REF_PARAM>"
  }
}

6. Send a message with user_ref

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.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "user_ref":"<UNIQUE_REF_PARAM>"
  }, 
  "message": {
    "text":"hello, world!"
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>" 

On success, the Send API will respond with a message_id:

{
  "message_id": "mid.1456970487936:c34767dfe57ee6e339"
}

7. Handle the user response

When the message is successfully delivered, the user will receive a push notification and a new chat will be opened with a reminder that they opted-in to your bot:

If the user responds to your message, the appropriate event (messages, messaging_postbacks, etc.) will be sent to your webhook, with a prior_message object appended. The prior_message object includes the source of the message the user is responding to, as well as the user_ref used for the original message send.

For example, the following messages event would be sent to your webhook if the user responded with a text message:

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"mid.1457744567618:41d102a3e1ae206a38",
    "text":"Thanks for messaging me!"
  },
  "prior_message": {
    "source":"checkbox_plugin",        
    "identifier":"<USER_REF>"
  }
}

Customizing Default State

The default state can be set at render-time to make it either an opt-in or opt-out experience. Be aware local law in some jurisdictions may require an opt-in experience when using the checkbox plugin to send marketing or promotional communications. You are responsible for ensuring your use of the plugin complies with applicable law.

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.

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) otherwise the plugin will be hidden.
5. Testing on localhost is not supported right now.