Facebook message channels

Setup

Facebook messages are built using a webhook template. The setup for both simple messages and rich messages is the same, see the Webhooks quick start guide for the initial setup.

For facebook, the URL to use (taken from the Facebook Messenger API docs) is https://graph.facebook.com/v2.6/me/messages?access_token=************************.

The Request body type is always Raw Text, with the parameters supplied in JSON format, detailed in the following sections for simple and rich messaging.

Finally, this API requires one header. Click Add header and set the key to Content-Type and the value to application/json.

Simple message channel

In the example below you can see how a simple facebook messenger channel is built using a webhook template.

The request body parameters for this Messages endpoint are:

• recipient: Name of the JSON Object containing params for the user that the message is to be sent to
  • id: the Facebook Messenger ID of the user. This is being pulled in from your users profile via the personalisation syntax {{fb_messenger_id}}
• message: Name of the JSON Object containing params for the message content
  • text: The text of the message to be sent

{
  "recipient": {
    "id":"{{fb_messenger_id}}"
  },
  "message": {
    "text": "Your Message here"
  }
}

The simple message style appears like a notification on the lock screen on mobile and appears in the messenger app on mobile or web as shown below: 

Rich message channel

This rich message style will have elements that appear as in the example below on Facebook Messenger. It uses a template Facebook Messenger call the generic template:

There are host of additional rich message types you can build, these are covered in more detail in the facebook messenger docs and include: 

• List Template
• Media Template
• Receipt Template
• Airline Templates

The list template is great for news updates for publishers, the media template allows you to send video and other rich media, the receipt template is great for sending receipts for e-commerce and the airline templates cover use cases like boarding passes etc.

The request body parameters for this messages endpoint include:

• recipient: Name of the JSON Object containing params for the user the message is to be sent to

  • id: the facebook Messenger ID of the user. This is being pulled in from your user's profile via the personalisation syntax {{fb_messenger_id}}

• message: Name of the JSON Object containing params for the message content

  • attachment: JSON Object for message with rich content attached

    • type: attachment type "template" for this example

    • payload:  JSON Object for message payload

      • template_type: the type of template used is "generic" for this example. For more on the facebook messenger generic template see docs

      • elements: JSON Array with objects for individual elements of message

        • image_url: the URL of the image 

        • title: title of message appears below image

        • subtitle: the subtitle that appears below the title

        • buttons: the CTA buttons that appear below the subtitle

📘

FB rich message parameters

Parameters can have multiple elements. There is an example JSON for a rich message with two elements further down in this article).

{
  "recipient": {
    "id": "{{fb_messenger_id}}"
  },
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type":"generic",
        "elements": [
          {
            "title": "YOUR TITLE HERE",
            "image_url": "YOUR IMAGE URL HERE",
            "subtitle": "YOUR SUBTITLE HERE",
            "buttons": [
              {
                "type": "web_url",
                "url": "YOUR LINK HERE",
                "title": "BUTTON TEXT HERE"
              }
            ]
          },
          ...... ADDITIONAL ELEMENTS
        ]
      }
    }
  }
}

You can use sample message below based on content from xtremepush's blog to quickly test this style of message.

{
  recipient: {
    id: recipientId
  },  
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
        "elements": [
          {
            "title": "Geofencing vs iBeacons",
            "image_url": "https://d2duw1tbgzwwah.cloudfront.net/wp-content/uploads/2017/10/geo-vs-beacons-750x500.jpg?resize=720%2C346&ssl=1",
            "subtitle": "Which best suits your Business?",
            "buttons": [
              {
                "type":"web_url",
                "url":"https://xtremepush.com/xtremepush-geofencing-ibeacons/",
                "title":"Read More"
              }
            ]
          },
          {
            "title": "GDPR – The Practicalities of a New Reality",
            "image_url": "https://d2duw1tbgzwwah.cloudfront.net/wp-content/uploads/2017/05/GDPR-Practicalities-NEWS-750x423.png?resize=1250%2C600&ssl=1",
            "subtitle": "There are now about 380 days until GDPR is ‘the new reality",
            "buttons": [
              {
                "type":"web_url",
                "url":"https://xtremepush.com/gdpr-get-gdpr-compliant/",
                "title":"Read More"
              }
            ]
          }
        ]
      }
    }
  }
}

The rich message style style appears in the messenger app on mobile or web as shown below (message with images and read more CTA below are from example above ). 

👍

Facebook webhook templates

As a best practice, once your webhook is getting responses in the 20x response code range and working as expected it is recommended to copy its content (all the configured settings except for the message text) and save it as a template. This will allow you to quickly select it from the webhook tab in the campaign builder.