Checkbox Plugin

This document explains how to programmatically add the Checkbox Plugin in a form on your website for a person to allow your business to send messages via Messenger from Meta.

How It Works

Your business can ask a person to opt-in, allow your business to send messages, from a form on your website. This can be a transactional form, such as confirming items in a cart, or a promotional form, such as asking for notifications for sales and product releases.

If a person has opted in to receive promotional messages, your business can send one notification a day. If the person has opted in to receive transactionals messages, your business can send messages only within the standard 24-hour messaging window. To continue to send messages outside the standard 24-hour messaging window, your messages must include message tags.

When a person visits a form on your website the checkbox can be displayed. The person can check the box, opt in, or not, then submit the form. If the box is checked and the form is submitted, the person is opted in. Upon submission webhook notifications can be sent to your business to give you the state of the checkbox, checked or unchecked, and information that allows you to send a message to the person.

If the person is currently logged in to Facebook, their profile photo and name will be displayed below the checkbox. This is the profile that will receive the messages from your business. Note that for transactional opt-ins, the profile will only be shown if the persons' browser privacy settings and Facebook account sharing settings allow. For promotional opt-ins, the profile will only appear after the person clicks the checkbox, if browser privacy settings allow.

The person can change the profile that is logged in to Facebook by clicking the "Not you?" link to log out. Clicking the link will clear the active Facebook session and present a login dialog for the person to login.

If the person is not logged in to Facebook, a profile will not be displayed in the plugin. When the checkbox is selected, the person will be prompted to login. You can also hide the checkbox if a person is not logged in to Facebook.

Webhook Notifications

When a person selects the checkbox and submits the form, a webhook notification will be sent to your server that contains whether the opt in type is for promotional or transactional messages.

Promotional webhook notifications contain:

A notification message token used to send messages to the person who has opted in

Transactional webhook notifications contain:

A unique reference parameter that represents the person who has opted in

Before You Start

This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.

Your app will need:

A Page access token requested from a person who can perform the MESSAGING task on the Page
The pages_messaging permission
The Facebook SDK for Javascript on each webpage you want the checkbox to appear
Subscribe to the messaging_optins webhook
The opt-in must be triggered by a user action, such as a button press
Clear opt-in messaging that explains the type of messaging the person is opting in to and the cadence of the messaging
Compliance with the Platform policies and Community Standards .

Limitations

Testing on localhost is not supported.

Apps with Standard Access can only send and receive messages from people who have a role on your app. Additionally Pages in unpublished status will only be allowed to message people with a role on the Page.

If your app has Standard Access, the plugin will only be rendered for people who have a role on your app, a role on the Facebook Page, and who are logged into their Facebook account.

It is your responsiblity to 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.

For any messages sent outside the standard 24-hour messaging window, message tags must be included.

Add the Plugin

We recommend placing the checkbox above the button that will submit the form. Placing the plugin below the button can create confusion and may result in the person not understanding that they have opted-in. As a result, the person may report or block your business when they receive messages.

Add the following code to each webpage where you want to display the checkbox.

Transactional Form Example

<body>
...
  <div class="fb-messenger-checkbox"  
    page_id=PAGE-ID
    messenger_app_id=APP-ID
    opt-in-type="transactional"
    ref="ADDITIONAL-INFORMATION"
    user_ref="UNIQUE-REF-PARAM"
    allow_login="true"
    size="standard"
    skin="dark"
    center_align="true">
  </div>
...
</body>

Promotional Form Example

<body>
...
  <div class="fb-messenger-checkbox"  
    page_id=PAGE-ID
    messenger_app_id=APP-ID
    opt-in-type="promotional"
    promotional-frequency="daily"
    promotional-topic="YOUR-TOPIC"
    ref="ADDITIONAL-INFORMATION"
    user_ref="UNIQUE-REF-PARAM"
    allow_login="true"
    size="standard"
    skin="dark"
    center_align="true">
  </div>
...
</body>

The user_ref parameter identifies the person who is logged in and is passed to your website to identify the person. This parameter should be unique not just for every person, but for every time the plugin is rendered. If the parameter is not unique, then the plugin may not render.

Available Attributes

Attribute Description

allow_login

bool

Allow the person to login to Facebook if not already logged in. Defaults to true If you set allow_login to false, then the plugin will not render for people who are not logged in.

class

enum

Required

Value must be fb-messenger-checkbox

center_align

bool

Aligns profile image and text to the left (false) or in the center of the plugin (true). Defaults to false

messenger_app_id

int

Required

The ID for Facebook App linked to your Facebook Page

opt-in-type

enum {promotional, transactional}

The promotional opt-in type allows your app to send messages on a daily cadence. The transactional opt-in type allows your app to send messages within the standard 24-hour messaging window. Defaults to transactional if not set.

page_id

int

Required

The ID for the Facebook Page associated with your business

promotional-frequency

enum {daily}

The cadence at which your app can send messages to a person who has opted in to receiving messages from your business. Required when using the promotional opt-in type and must be set to daily

Message Frequency

Beginning January 31, 2023, the promotionaly-frequency attribute must be set to daily.

promotional-topic

string

The topic for your promotional messages. For example, sales or coupons. Required when using the promotional opt-in type

ref

string

Additional information to be returned in the webhook notification. Valid characters are a-z A-Z 0-9 =-_

size

enum {small, medium, large, standard, xlarge}

Size of plugin. Defaults to large

skin

enum {light, dark}

Sets the color theme for the plugin content.

light (default) – Plugin renders with white background, dark text, and multi-colored Messenger icon.
dark – Plugin renders with dark background, white text, transparent Messenger icon

user_ref

string

Required

Unique parameter for referencing a user. A maximum of 250 characters is allowed. Valid characters are a-z A-Z 0-9 +/=-._

Log Checkbox States

You can subscribe to events involving the checkbox on your webpage. Add the following code to each webpage to track checkbox changes.

<body>
...
  <script>
    window.fbAsyncInit = function() {
      FB.init({
        appId      : 'APP-ID',
        xfbml      : true,
        version    : 'API-VERSION'
      });

      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");
        }
      });
    }; 
  </script>  
...
</body>

Confirm Opt-In

You must send a checkbox confirmation event only after the person has opted in. Your business can only send messages to a person after the person has opted in.

The following code uses App Events to confirm the opt-in.

<html>
  <head>
    ...
    <script>
        function confirmOptIn() {
          FB.CheckboxPlugin.confirm({
            'app_id':'APP-ID',
            'page_id':'PAGE-ID',
            'ref':'ADDITIONAL-INFORMATION,
            'user_ref':'UNIQUE-REF-PARAM'
          });
      }
    </script>
    ...
  </head>

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

It is not required to verify the state of the checkbox before doing so.

Opt In Webhook Notifications

Subscribe to the messaging_optins webhook events to receive a notification when a person opts in.

When a person clicks the checkbox to allow your business to send messages then submits the form, we will send a webhook notification to your server. The contents of this notification are dependent on the opt-in type, promotional or transactional.

Promotional Opt-In Example

The following webhook notification contains information about a promotional opt-in with a daily messaging cadence, allowed to send one message per day to the person.

"object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1649870243065,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1649870242894,
                    "optin": {
                        "type": "notification_messages",
                        "payload": "",
                        "notification_messages_token": "MESSAGE-TOKEN",
                        "notification_messages_frequency": "daily",
                        "topic": "NOTIFICATION-MESSAGE-TOPIC",
                        "token_expiry_timestamp": 1652462124190,
                        "ref": "ADDITIONAL-INFORMATION",
                        "user_token_status": "NOT_REFRESHED",
                        "notification_messages_status": "RESUME_NOTIFICATIONS"
                    }
                }
            ]
        }
    ]

Transactional Opt-In Example

The following webhook notification contains information about a transactional opt-in allowing your app to send messages within the 24-hour standard messaging window.

"object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1649870243065,
            "messaging": [
                {
                  "recipient":{
                     "id":"PAGE-ID"
                  },
                  "timestamp":UNIX-TIMESTAMP,
                  "optin":{
                      "ref":"PASS-THROUGH-PARAM",
                      "user_ref":"UNIQUE-REF-PARAM"
                  }
                }  
            ]
        }
    ]

Send a Message

The opt-in type determines how often you can send messages to a person who has opted in. When the message is successfully delivered, the person will receive a push notification, if the person allows push notifications, and a new chat will be opened with a reminder that the person opted in to receive messages from your business.

Transactional Messaging

For transactional opt-in type messaging, you will use the user_ref value you receive in the message_optin webhook notification as the recipient value to send a person messages. These messages must be sent within the standard 24-hour messaging window of when the person has opted in.

Promotional Messaging

For promotional opt-in type messaging, you will use the notification_messages_token value you receive in the message_optin webhook notification as the recipient value to send a person recurring messages.

Send Marketing Messages

Visit the Recurring Notications guide and the Page Messages Reference for more information on sending recurring messages.

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "user_ref":"UNIQUE-REF-PARAM"
  }, 
  "message": {
    "text":"Thank you for your purchase!"
  }
}' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"

On success, your app will receive the following JSON response:

{
  "message_id": "mid.1456..."
}

If the person responds to your message, any webhooks that are sent will include the prior_message object with the identifier set to the user_ref value.

For any messages sent outside the standard 24-hour messaging window, message tags must be included.

Example Webhook Notification

The following example webhook notification was sent when a person responded with a text message to the transactional opt-in type message sent by your business.

{
  "sender":{
    "id":"PSID"
  },
  "recipient":{
    "id":"PAGE-ID"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"mid.145...",
    "text":"Thanks for messaging me!"
  },
  "prior_message": {
    "source":"checkbox_plugin",        
    "identifier":"USER-REF"
  }
}

Note that the first message sent to a person after opt-in is added to your Page Inbox only if the person replies to the message and the timestamp will appear the same for the message and response.

Troubleshooting Tips

If you're having trouble getting the plugin to properly render, check the following:

Verify that your app is approved for the pages_messaging permission. Limitations apply if your app has Standard Access.
Verify that your app is subscribed to messaging webhooks.
Verify that you whitelisted your website domain. You will see "Refused to display *** in a frame because an ancestor violates the following Content Security Policy directive: ***" if your domain is not whitelisted.
If the allow_login parameter is set to false the plugin will be hiddedn unless you are logged in to Facebook.
Testing on localhost is not supported.
Only set xfbml in only one place, either set it to true in FB.init or in the SDK url, https://connect.facebook.net/en_US/sdk.js#xfbml=1.

Checkbox Plugin

How It Works

Webhook Notifications

Before You Start

Limitations

Add the Plugin

Transactional Form Example

Promotional Form Example

Available Attributes

Log Checkbox States

Confirm Opt-In

Opt In Webhook Notifications

Promotional Opt-In Example

Transactional Opt-In Example

Send a Message

Transactional Messaging

Promotional Messaging

Send Marketing Messages

Example Request

Example Webhook Notification

Troubleshooting Tips

See Also