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.
A page access token with pages_messaging
permission is required to send messages to people.
Apps in Development Mode, are restricted to message people that have a role in the app. Additionally Pages in unpublished
status will only be allowed to message people with a role on the Page.
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.
Review and follow our best practices regarding usage and placement of the plugin.
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.
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 our Platform policies and Community Standards. This includes ensuring your use of the plugin respects user privacy, and abides by all applicable local laws and regulations.
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.
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"
page_id=<PAGE_ID>
messenger_app_id=<APP_ID>
user_ref="<UNIQUE_REF_PARAM>"
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.
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"); } }); };
The MessengerCheckboxUserConfirmation
event must only be sent after the user has actively opted-in with an action, such as button press or form submission.
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
). Only alphanumeric characters as well as -, _, and = are supported.
<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>
messaging_optins
webhook eventAfter 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>"
}
}
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"
}
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>"
}
}
Note that the first message sent by the page, or prior_message
at this step, gets added to the Page inbox only if the user replies to the message. As a consequence, for the Page, the time of the first message will appear as sent at the same time as the response
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.
Note that the plugin will render without a Facebook session only if the app is approved and public.
If you're having trouble getting the plugin to properly render, try the tips below:
pages_messaging
permission. 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. xfbml
to true in only one place. Either set it to true in FB.init
OR set it in the SDK url like so https://connect.facebook.net/en_US/sdk.js#xfbml=1
.