Facebook Messenger

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 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
• Checkbox Plugin - Not currently supported

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