From Webpage

Chat Plugin

You can place customer chat plugin for Facebook Messenger to let users contact you directly from your web pages. When the user is logged in to Facebook, he can directly write to you. Otherwise the login popup is displayed.

The advantage is that all the recent history is displayed in the chat. Also you don't need to capture any personal information to follow up after the user leaves.

Setup

1. Setup Facebook JavaScript SDK

See documentation below.

2. Whitelist Origin Domain

Whitelist the domain where this plugin will be displayed.

🚧

Domain Whitelist Requirements

• This plugin has to be served over HTTPS.
• Use a fully qualified domain name, such as https://www.messenger.com/. IP addresses and localhost are not supported for whitelisting.

3. Render the Plugin

<div class="fb-customerchat"
 page_id="<PAGE_ID>">
</div>

4. Listen for Postback and Message Received Webhook

If a new conversation is started via the plugin, and you have set up the Get Started Button, you will receive a Postback Received webhook when the user clicks the get started button.

If the user sends you a message, you will receive Message Received webhook.

5. Customize the Plugin

You can set theme color, display behaviour, etc. using plugin attributes. See Facebook documentation for more detail.

Send to Messenger Button

You can use this plugin to bind Facebook Messenger account with users in your application. This plugin places a button on your site. When the user clicks on it, it fires Opt-in webhook which you can listen to and get the user's id for further communication.

Setup

1. Setup Facebook JavaScript SDK - see documentation below.
2. Put the button plugin code to place where it should be displayed.

<div class="fb-send-to-messenger"
     messenger_app_id="{{FACEBOOK_APP_ID}}"
     page_id="{{PAGE_ID}}"
     data-ref="{{PASS_THROUGH_PARAM}}"
     color="blue"
     size="standard">
</div>

🚧

data-ref has to use single quote if you send data using JSON. This ensures that the HTML is valid and button is displayed properly.

📘

Button can be localized by setting locale of sdk.js, i.e. js.src = "//connect.facebook.net/cs_CZ/sdk.js";. See Facebook documentation for more details.

Button Text

You can change text of the button from pre-defined strings using cta_text attribute.

Moreover, when the cta_text attribute is used, most signed-in users will only have to click the plugin button itself to opt in, without having to re-confirm with the popup, and the Opt-in webhook will be delivered immediately.

The following values are supported:

JavaScript Events

You can subscribe to JavaScript events using this code:

<script>
  FB.Event.subscribe('send_to_messenger', function(e) {
    // callback for events triggered by the plugin
  });
</script>

Webhooks

This plugin triggers Opt-in webhook.

Checkbox

Checbox Plugin is another convenient way how to bind a Messenger user into your application. For example, you can place this checkbox on the final page of your e-shop order process to allow user receive shipping details into Messenger.

Similarly to Send to Messenger Button, it recognise if user is logged-in on Facebook and place user's name and profile picture underneath. Checkbox can be checked by default so that user doesn't have to check it actively.

This Facebook plugin is quite difficult to implement so we'll guide you through the whole process.

How it works

When a person is logged into Facebook, his session will be detected and his 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. The user can change the identity by clicking on "Not you?" link.

When the user is not logged in, he will be asked to do so.

Setup

1. Setup Facebook SDK for JavaScript
2. Render the Plugin
3. Whitelist Origin Domain
4. Listen for Plugin Events
5. Confirm Opt-in
6. Listen for Opt-in webhook
7. Send Message
8. Get User's Response

1. Setup Facebook SDK for JavaScript

See documentation below.

2. Render the Plugin

<div class="fb-messenger-checkbox"
     messenger_app_id="{{FACEBOOK_APP_ID}}"
     origin="{{YOUR_PAGE_DOMAIN}}"
     page_id="{{PAGE_ID}}"
     prechecked="false"
     allow_login="true"
     user_ref="{{STRING_UNIQUE_FOR_EVERY_RENDER}}"
     size="small"></div>

3. Whitelist Origin Domain

Whitelist the domain you've set in origin attribute (see Render the plugin above).

4. Listen for Plugin Events

FB.Event.subscribe('messenger_checkbox', function (event) {
        console.log('FacebookService - Event "messenger_checkbox"', event)
        const userRef = event.user_ref

        if (event.event === 'rendered') {
          console.log('FacebookService - Event "messenger_checkbox" - Plugin was rendered')
        } else if (event.event === 'checkbox') {
          const checkboxState = event.state
          console.log('Checkbox state: ' + checkboxState)
        } else if (event.event === 'not_you') {
          console.log('User clicked \'not you\'')
        } else if (event.event === 'hidden') {
          console.warn('Plugin was hidden. This usually means a problem in FB or integration... Did you whitelist your domain? When using a FB dev app is your FB account registered developer/tester/admin? Have generated a unique `user_ref` for this render? And maybe more...')
        }
 })

5. Confirm Opt-in

To actually trigger the Opt-in Webhook you have to send MessengerCheckboxUserConfirmation event. You don't have to check the state of the checkbox it will be automatically checked by Facebook.

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

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

</html>

6. Listen for Opt-in Webhook

When an event from previous state is sent, you will receive the Opt-in webhook call. You can pair your user using data.contact.user_ref that will contain the generated string that you provided as user_ref in previous steps.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "facebook_messenger"
    },
    "contact": {
      "user_ref": "{{STRING_UNIQUE_FOR_EVERY_RENDER}}" // set on frontend 
    },
    "opt_in": {
      "type": "checkbox",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}

7. Send Message

You can send message to user using the user_ref attribute.

{
  "contact": {
    "user_ref": "{{YOUR_CUSTOM_USER_REF}}"
  },
   "channel": {
    "id": "{{CHANNEL_ID}}"
  },
   "content": {
    "type": "text",
    "payload": "You just signed in to our FB Page!"
  }
}

📘

Life Time of the user_ref

At the time of writing this tutorial, it seems that Facebook keeps the old user_refs forever. However, there is no clue for how long they will keep them. Amio uses this attribute to send messages until the facebook contact id is received (see next chapter for more details).

8. Get User's Response

To finish the full procedure of opt-in, the user has to reply you back. If this happens, you will receive a Message Received and Amio gets facebook contact page scoped id (PSID) which is used for further communication.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "{{MESSAGE_ID}}",
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "{{CONTACT_ID}}",
      "user_ref": "{{STRING_UNIQUE_FOR_EVERY_RENDER}}",
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    }
  }
}

Troubleshooting

Sometimes checkbox plugin is not displayed at all and it is quite hard to investigate where is the cause of the problem. For this situation, we created a troubleshooting list which should help you implementing this feature.

👍

Contact our support team [email protected] if you cannot make this plugin work.

1. user_ref has to be always unique. (Even for every single page refresh!)
2. Check if the domain you're displaying the checkbox in has been whitelisted. In case you call your form from a similar domain https://your-domain.com/facebook/facebook.aspx then whitelist https://your-domain.com/facebook too!
3. 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.
4. Is the origin attribute the same as the domain where you host the plugin?
5. Testing on localhost is not supported by Facebook right now. You can overcome this by using Ngrok however.
6. Check that appId in Facebook Javascript SDK and messenger_app_id in Checkbox - 2. Render the plugin has the same values.

Message Us Button

Message Us button can be used on your sites to let the users contact you on Facebook Messenger channel. On the desktop browser, the user is sent to messenger.com and on mobile they are sent to the Messenger native app.

Setup

1. Setup Facebook JavaScript SDK - see documentation below.
2. Put the button plugin code to place where it should be displayed.

<div class="fb-messengermessageus"
     messenger_app_id="1806054702946735"
     page_id="{{PAGE_ID}}"
     color="blue"
     size="standard">
</div>

Webhooks

This plugin does not trigger a webhook callback. However, you will receive a Message Received webhook when the user sends a message to your page.

Messenger Link

You can use Messenger links to send them via SMS, email, or anywhere else to help someone find you more easily within Messenger. The link format is https://m.me/username.

You can use Messenger Link to:

• pair a FB Messenger user to a session or an account in an external app.
• to direct the user to specific content or features available within the bot.

A m.me link with an added parameter looks like this:

http://m.me/<PAGE_NAME>?ref=<REF_PARAM>

📘

Facebook Page Username

Username of your Facebook Page can be set in administration, see Facebook instructions.

Facebook JavaScript SDK

To make Facebook plug-ins work, you have to include Facebook JavaScript SDK into your website. Place following code directly after the opening tag <body>. See Facebook Documentation for more details. Beware that some Javascript frameworks have their own libraries to include Facebook SDK.

<body>
  <script>
  window.fbAsyncInit = function() {
    FB.init({
      appId: "{{FACEBOOK_APP_ID}}",
      xfbml: true,
      version: "v2.11"
    });
  };
    
  (function(d, s, id){
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) { return; }
    js = d.createElement(s); js.id = id;
    // js.src = "//connect.facebook.net/en_US/sdk.js"; // whole SDK
    js.src = "//connect.facebook.net/en_US/sdk/xfbml.customerchat.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'facebook-jssdk'));
  </script>
  ...
</body>

You can also use this great library - lazy-fb.

// npm install --save lazy-fb

lazyFB({
        appId: {{FACEBOOK_APP_ID}},
        autoLogAppEvents: true,
        xfbml: true,
        version: 'v2.11',
        sdkModule: 'xfbml.customerchat'
})

📘

Localization

Button can be localized by setting locale of sdk.js, i.e. js.src = "//connect.facebook.net/cs_CZ/sdk.js";. See Facebook documentation for more details.