Enable the Webhook Channel

The Webhooks channel is required in order to enable social messaging. If you are not familiar with this channel Check the Webhooks - Quick Start Guide. Secondly you will need an account, credentials and API documentation for the service you want to send messages with. You can build your social messaging channel using a webhook template, mapped to a social messaging  providers API. In the next section we detail sample social messaging channels built using different providers.

Create a Facebook Messaging Channel

We have documented Facebook messenger as a sample Social Messaging provider that can be integrated with the xtremepush platform.

• Simple FB Message Channel 
• Rich FB Message Channel

You can see both a simple text message and an example of a rich message with images and CTAs in the examples below.

If you want to use another provider you can simply build a channel template based on that provider API for sending messages similar to examples above. If you need help integrating with your service provider please contact your account manager.

Once your channel is set up you now need to opt-in some users. The process for this varies based on the provider but in general you will need to embed a social plug-in on your site or in your app so you can opt-in users and you will need to capture opt-in details and send them to xtremepush. Ideally your messenger should be powered by a chatbot automates conversations and provides an intuitive UX. This allows a single integration point for xtremepush even if you distribute your chatbot in multiple messaging channels.

Add a social messaging plug-in

We will again use Facebook messenger as an example for opting in users. Review the Facebook messenger Docs for embedding a plug-in and opt-ing in users. You can find these in the discovery and re-engagement section.

For this example we will work with the send to messenger plugin :

It is possible to work with other plugins:

• Working with Customer Chat Plugin

 Follow the facebook messenger docs for embedding the send to messenger plugin on your site to opt-in users for messaging. We are also assuming you already have the xtremepush SDK on your site (if not details on deploying SDK here). You will need to modify the plugin embed code to allow syncing of opted in users to xtremepush. To be able to connect the user to xtremepush and enable you to message them on FB Messenger via your FB messenger channel you need to grab the xtremepush id and set the plugins data-ref attribute to be equal to the xtremepush id.

See highlighted line below where we use xtremepush SDK method to get ID. Setting this attribute is key as once set it means the xtremepush id is available in your chatbot when the user opts in.

var fbPluginElements = document.querySelectorAll(".fb-send-to-messenger[page_id='XXXXXXXXXXX']");
 if (fbPluginElements) {
 for (i = 0; i < fbPluginElements.length; i++) {
 fbPluginElements[i].setAttribute('data-ref', xtremepush('get','device_info').id );
 }
 }

Once the users id is pushed to your chatbot as part of the opt-in then you can easily sync your user with the chatbot. The full example of javascript associated with the facebbook SDK and send to messenger opt-in is below:

window.fbMessengerPlugins = window.fbMessengerPlugins || {
    init: function() {
        FB.init({
            appId: "XXXXXXXXXXXXXXXX",
            xfbml: true,
            version: "v2.10"
        });
     
       FB.Event.subscribe('send_to_messenger', function(e) {
    	// callback for events triggered by the plugin
          console.log("send_to_messenger event");
          console.log(e);

            if (e.event == 'rendered') {
                console.log("Plugin was rendered");
            } else if (e.event == 'opt_in') {
                var checkboxState = e.state;
                console.log("Checkbox state: " + checkboxState);
                if (checkboxState == 'checked') {
                    window.confirmOptIn();
                } else if (checkboxState == 'unchecked') {}
                console.log(FB.getUserID());
            } else if (e.event == 'not_you') {
                console.log("User clicked 'not you'");
            } else if (e.event == 'hidden') {
                console.log("Plugin was hidden");
            }         
  		});
    },
    callable: []
};
window.fbMessengerPlugins.callable.push(function() {
  
  
  	var  fbPluginElements = document.querySelectorAll(".fb-send-to-messenger[page_id='XXXXXXXXXXXXXXXX']");
   if (fbPluginElements) {
     for (i = 0; i < fbPluginElements.length; i++) {
       fbPluginElements[i].setAttribute('data-ref', xtremepush('get','device_info').id );
     }
   }
});
window.fbAsyncInit = window.fbAsyncInit || function() {
    window.fbMessengerPlugins.callable.forEach(function(item) {
        item();
    });
    window.fbMessengerPlugins.init();
};
setTimeout(function() {
    (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";
        fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'facebook-jssdk'));
}, 0);

Integrate xtremepush with your Chatbot to opt-in users

We have created a sample bot to demonstrate how you can integrate xtremepush with your bot. This bot is based on the sample bot in the facebook messenger quick start guide. You will see in the facebook docs one option is to remix the facebook messenger sample bot on glitch. This means you do not need a server to deploy your sample bot to, Glitch will provide a public URL served over HTTPS for your bot. We have modified the facebook sample to include an integration with xtremepush. To create your own version of this bot on Glitch, do the following:

• Open our starter webhook project on Glitch:

This will allow you to setup the standard facebook demo bot as per their docs but with xtremepush integrated out of the box. The modified bot has the following change to support integration with xtremepush.

In addition to setting the credential required to connect your bot to facebook messenger in the .env file you need to:

• also set XP_ACCESS_TOKEN in the .env file using the App token from App Settings > General Settings in your project on the xtremepush platform

The xtremepush integrated bot uses the id passed back from the opt-in to send a fb_messenger_id to the xtremepush platform. This is the id used to target recipients when creating channels as described in section 2 above.

In the bot.js there is a simple wrapper function around the xtremepush external API method for syncing attributes:

function sendXPAttribute(xpID, attributeText, attributeValue) {
  var postData = { 
    apptoken: process.env.XP_ACCESS_TOKEN ,
    device_id: xpID,
    tag: attributeText,
    value: attributeValue
  };

  callXPPostDataAPI(postData);
}


function callXPPostDataAPI(jsonData) {
  request({
    uri: 'https://external-api.xtremepush.com/api/external/hit/tag',
    method: 'POST',
    json: jsonData

  }, function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log("Successfully registered recipient with xtremepush");
    } else {
      console.error("Unable to register.");
      console.error(response);
      console.error(error);
    }
  });  
}

This can use the xtremepush id to target an attribute update for a user. And it is used in this way in a method in the bot that can initialises a user on xtremepush after an opt-in event. In this example we also use the Facebook graph api to retrieve a few additional user params and we sync those with xtremepush along with the messenger id:

function initialiseProfile(PSID, xpID) {
  request({
    uri: 'https://graph.facebook.com/v2.6/' + PSID,
    qs: { access_token: process.env.PAGE_ACCESS_TOKEN },
    method: 'GET',
    json: {"fields":"first_name, profile_pic, gender, is_payment_enabled"}  

  }, function (error, response, body) {
    if (!error && response.statusCode == 200) {
      var first_name = body.first_name;
      var last_name = body.last_name;
      var gender = body.gender;
      var profile_pic = body.profile_pic;
      
      sendXPAttribute(xpID, "fb_messenger_id", PSID); 
      sendXPAttribute(xpID, "first_name", first_name); 
      setTimeout(function() {sendXPAttribute(xpID, "last_name", last_name)},10000);
      setTimeout(function() {sendXPAttribute(xpID, "gender", gender)},20000);
      setTimeout(function() {sendXPAttribute(xpID, "profile_pic", profile_pic)},30000);
      
      sendTextMessage(PSID, first_name + ", thanks for opting into to receive updates from xtremepush we'll send you news and product updates." );     
      typingToggle(PSID, "typing_on");  
      setTimeout(function() {sendGenericMessage(PSID)},10000);  
      setTimeout(function() {sendTextMessage(PSID, "They'll look something like this")},20000);  
      setTimeout(function() {typingToggle(PSID, "typing_off")}, 30000);  
    
      } else {
      sendXPAttribute(xpID, "fb_messenger_id", PSID); 
      sendTextMessage(PSID, "Thanks for opting into to receive updates from xtremepush we'll send you news and product updates.");  
      typingToggle(PSID, "typing_on");  
      setTimeout(function() {sendGenericMessage(PSID)},10000);  
      setTimeout(function() {sendTextMessage(PSID, "They'll look something like this")},20000);  
      setTimeout(function() {typingToggle(PSID, "typing_off")}, 30000);  
        
      console.error("Unable to retrieve data.");
      console.error(response);
      console.error(error); 
    }
  });  
}

The method used to initialise a user is called from the method that handles opt-in events the xtremepush id is available as it has been passed in as outlined in the previous section.

 function receivedOptin(event) {
  var pageID = event.recipient.id;
  var timeOfMessage = event.timestamp;
  var optin = event.optin;
  var userRef = optin.user_ref;
  var xpID = optin.ref;
  var PSID = event.sender.id;
  
  if (event.sender){
  console.log("Received optin for xtremepush user %d and page %d at %d with message:", 
    xpID, pageID, timeOfMessage);
  console.log(JSON.stringify(optin));
    
  initialiseProfile(PSID, xpID);  
  }
  else {
  
  console.log("Received optin for user %d and page %d at %d with message:", 
    xpID, pageID, timeOfMessage);
  console.log(JSON.stringify(optin));
  sendOptinMessage(userRef, "Thanks for opting into to receive updates from xtremepush", xpID)
  sendXPAttribute(xpID, "fb_user_ref", userRef); 
}

Once you have your bot integrated and are in a position to capture some user ids from the social messenger you are now ready to test sending some messages. 

Testing Social Messaging

To test social messages create your campaign the way that you normally would. Select the webhook channel and on the webhook channel page pick your Messaging template:

You can target test user(s). For example for a Facebook Messenger channel like below:

You can target your own facebook messenger based on a segment that targets your user if you know your id. Details on how to upload test users with the necessary attributes and target them can be found in:

• Set up test user profiles

Run a test and you should receive your test message to facebook messenger. If you have any errors troubleshoot them as described in the webhook guide. Your messenger channel can be added as a complimentary channel to a campaign that also includes a notification or another comms channel. One common use case is to use the messenger channel as a fallback channel for users who have not opted-in to other notifications. The messenger channel can be trigged just like other channels one use case for this is basket or other drop-off recovery type campaigns.

• Event triggered notifications
• Drop-off recovery type campaigns