Facebook Messenger

📘

Check out our quick start for using Facebook Messenger

For a guided example of how to use Facebook Messenger and get opt ins check out our quick start

Channel Identifier

In the API this channel can be referenced using: fbMessenger

This identifier can be used in the rules array, and customBody sections.

Enabling the Facebook Channel

See our Facebook channel setup guide for more information on how to setup for Facebook Messenger sending.

Obtaining a Facebook Messenger Id

To send a message via Facebook Messenger you must have the Facebook Messenger Id for the recipient, which is a unique numeric identifier for a Facebook user and your Facebook page combination.

Sending using a Facebook Messenger Id

To be able to send a message to a customer via Facebook Messenger you must obtain a unique Facebook Messenger Id for them and your page combination. This can be achieved in the following ways:

1. The customer elects to receive messages using the Facebook Send to Messenger plugin from a web page
2. The customer sends your Facebook page a direct message via Messenger
3. The customer clicks on the Message Us Facebook plugin and sends a message

Using the Facebook Web Plugins

🚧

Facebook European country restrictions

Please note that the Facebook Messenger Plugins are no longer available for use in European countries; please see the following Facebook article for an explanation.

Facebook provides web plugins you can easily add to your web site at appropriate points to invite customers to allow you to interact via Facebook Messenger with them. The plugins are:

• Message Us - takes the person directly to Messenger and allows them to initiate a conversation with you
• Send to Messenger - allows you to initiate a conversation with them in Messenger by providing a Facebook Messenger id for the customer via a webhook call
• Checkbox Plugin - Not currently supported

In order to use the Send to Messenger plugin with us you can use one of the following approaches:

1. Pass the profile id of the user securely with the Send to Messenger data and let us update the customer profile with their Facebook Messenger Id in the fbMessengerId attribute
2. Capture and record the Facebook Messenger Id yourselves for use with the Omnichannel API

Using the Send to Messenger web plugin with to opt-in

To use the Facebook Send to Messenger plugin with us we recommend doing the following:

Create secure meta data to use with the plugin

In order for our system to be able to update the correct user profile with the Facebook messenger Id received we need you to attach some secure meta data to the Facebook plugin call. To generate this data is a simple web service call as follows:

1. Ensure you have setup your Facebook page with us as detailed in the Facebook Messenger channel setup guide
2. From your server side call the Facebook Meta Data Service passing the profileId you want to attach the Facebook Messenger Id to, this is usually the logged user id. This service generates the secure meta data we can recognise.
3. Ensure that the secure meta data created in step 2 is passed into the Send to Messenger web control in the data-ref property e.g:

<div class="fb-send-to-messenger" 
  messenger_app_id="336037380081042" 
  page_id="PAGE_ID" 
  data-ref="**Add your secure meta data from step 1 here**" 
  color="blue" 
  size="standard">
</div>

4. Ensure that the Send to Messenger control is implemented in your web site according to the instructions. Note we will handle the Opt-in callback from Facebook for you, so no need to do this, and the messenger_app_id is set to 336037380081042

📘

How to find your Facebook pages page_id

There are many ways to do this you can find mentioned on the internet but the easiest is to use this website: https://findmyfbid.com

🚧

No Send to Messenger control rendered

The Facebook Send to Messenger web plugin only renders if it is happy with the parameters passed to it. Things to check are:

• messenger_app_id is set to our app id 336037380081042
• Your Facebook page has been configured in the portal as the Facebook channel
• Your Facebook page is published
• You have implemented the Facebook web plugin code correctly

Capturing the Facebook messenger Id yourself

Please see the following Facebook documentation about the Facebook web plugins for further instructions on how to achieve this, but you will be required to create a Facebook application and a web hook to receive the opt in data from Facebook.

Where can I find a customer Facebook Id after they have opted in?

We will automatically receive Facebook Ids as your users contact your Facebook page or click on Send to messenger widgets and store their Facebook Id in the customers profile in the fbMessengerId attribute.

If we cannot find any secure meta data with a Facebook opt-in or inbound message it will automatically create a profile for the user, so you can message them. If it does find secure meta data it will decode this and store the Facebook Id and information against the profile specified in the meta data.

In addition to storing the Facebook Id on the profile we will automatically retrieve the following details from Facebook:

• First name
• Last name
• Profile picture
• Locale
• Gender
• Timezone

This additional information is held in the facebook section of the users profile.

Sending a Facebook Messenger message

The Omnichannel API allows you to address customers on Facebook using one or more of the following:

• Customer Profile Id - This is the easiest option, we will automatically store the customer Facebook Id against their profile when they opt in to messages using the Send to Messenger widget or send an inbound message, and then use it when necessary
• Facebook Messenger Id - If you have already captured the customers Facebook Messenger Id for your Facebook page you can use this

We will always use a Facebook Messenger Id in preference to the profile id if included in the API call.

To test your channel you can call the Omnichannel API targeting the Facebook channel. To do this easily you could use a tool such as Postman or create the code in the language of your choice using the API reference docs.

The following are example request JSON can be used to perform a send:

{
  "to": {
    "profileId": "[email protected]"
  },
  "body": "My customer message via Facebook Messenger using a profile id",
  "rules": [
    "fbMessenger"
  ]
}

{
  "to": {
    "profileId": "[email protected]"
  },
  "body": "You account is now verified",
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "ACCOUNT_UPDATE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

{
  "to": {
    "fbMessengerId": "11112223333444444"
  },
  "body": "You account is now verified",
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "ACCOUNT_UPDATE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

{
  "title": "Your order has been dispatched",
  "to": {
    "profileId": "[email protected]"
  },
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "POST_PURCHASE_UPDATE"
    }
  },
  "rules": [
    "fbMessenger"
  ],
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Your order: ABC1245 has been dispatched."
    },
    {
      "type": "image/png",
      "url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png"
    }
  ]
}

{
  "to": {
    "fbMessengerId": "11112223333444444",
    "mobileNumber": "441234123123",
    "firstName": "Dave",
    "lastName": "Smith"
  },
  "body": "You account is now verified",
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "ACCOUNT_UPDATE"
    }
  },
  "rules": [
    "fbMessenger",
    "sms"
  ]
}

🚧

You must specify a message tag or type

If you are not directly replying to an inbound message within a 24 hour period of receiving it, then you will need to specify either a messageTag and messagingType in your channel options for Facebook to consider delivering it.

See Messenger Platform Policy for more information on Facebook message types.

Channel Options

🚧

Now required for subscription messages

If you are sending messages to subscribed users, rather than conversing with them, then you must include the channel options block with the correct message tag and message type stated to ensure your message is received.

The following additional channel options can be used to control the email channels most common options. To use the channel options create a object with your options in the requests channelOptions section in the fbMessenger property:

{
  "to": {
    "profileId": "[email protected]"
  },
  "body": "Good news, your order #12345 has shipped.",
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "POST_PURCHASE_UPDATE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

{
  "to": {
    "profileId": "[email protected]"
  },
  "body": "Hi, how can we help?",
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "RESPONSE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

Custom Body

Facebook Messenger is capable of sending many types of messages including:

• Text
• Attachments
• Quick replies
• Buttons
• Templates
• Etc...

The Omnichannel API automatically creates a text based Facebook message if you only define the body property when sending a message, but you can send any of the Facebook message body types if you use the customBody property and define a fbMessenger object within it that complies with the Facebook Graph API's message object as defined in the Facebook docs. Essentially you can pass any Facebook message type you desire if you define this property, or let us automatically create you a basic text message.

Examples of sends using Facebook custom bodies are:

{
  "body": "Test from the Omnichannel API",
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "customBody": {
    "fbMessenger": {
      "attachment": {
        "type": "image",
        "payload": {
          "url": "https://scontent.xx.fbcdn.net/v/t1.0-1/p200x200/17156020_1871286216424427_1662368582524349363_n.jpg?oh=22685c22a19fc2e28e69634e6a920972&oe=592FD3D1"
        }
      }
    }
  },
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "RESPONSE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

{
  "body": "Test from the Omnichannel API",
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "customBody": {
    "fbMessenger": {
    "text":"Pick a color:",
      "quick_replies":[
        {
          "content_type":"text",
          "title":"Red",
          "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED"
        },
        {
          "content_type":"text",
          "title":"Green",
          "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN"
        }
      ]
    }
  },
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "RESPONSE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

{
  "body": "Test from the Omnichannel API",
  "to": {
    "profileId": "**YOUR USER PROFILE ID**"
  },
  "customBody": {
    "fbMessenger": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "receipt",
          "recipient_name": "Stephane Crozatier",
          "order_number": "12345678902",
          "currency": "USD",
          "payment_method": "Visa 2345",
          "order_url": "http://petersapparel.parseapp.com/order?order_id=123456",
          "timestamp": "1428444852",
          "elements": [
            {
              "title": "Classic White T-Shirt",
              "subtitle": "100% Soft and Luxurious Cotton",
              "quantity": 2,
              "price": 50,
              "currency": "USD",
              "image_url": "http://clipart-library.com/images/rcjKk9yni.png"
            },
            {
              "title": "Classic Gray T-Shirt",
              "subtitle": "100% Soft and Luxurious Cotton",
              "quantity": 1,
              "price": 25,
              "currency": "USD",
              "image_url": "http://clipart-library.com/images/yTkAjXk9c.png"
            }
          ],
          "address": {
            "street_1": "1 Hacker Way",
            "street_2": "",
            "city": "Menlo Park",
            "postal_code": "94025",
            "state": "CA",
            "country": "US"
          },
          "summary": {
            "subtotal": 75,
            "shipping_cost": 4.95,
            "total_tax": 6.19,
            "total_cost": 56.14
          },
          "adjustments": [
            {
              "name": "New Customer Discount",
              "amount": 20
            },
            {
              "name": "$10 Off Coupon",
              "amount": 10
            }
          ]
        }
      }
    }
  },
  "channelOptions": {
    "fbMessenger": {
      "messagingType": "MESSAGE_TAG",
      "messageTag": "POST_PURCHASE_UPDATE"
    }
  },
  "rules": [
    "fbMessenger"
  ]
}

Receipts and Inbounds

To receive feedback or inbound messages from Facebook sends please see the following:

Inbound Messages

Allows you to receive Facebook Messenger messages sent from phones or Facebook to your Facebook page. Messages are delivered to a URL of your choosing using our webhook system. See the Inbound event in the Message Events section for more details.

Receipts

If you need to to know the status of messages you've sent using one of our Omnichannel API, you can request that delivery receipts are forwarded to a URL of your choosing using our webhook system. See the events in the Message Events section for more details on the receipt events you can receive.

You can receive the following types of receipts:

• Sent
• Delivered
• Read
• Failed