Sending to Messenger.
Channel identifier
In the Enterprise Communications API this channel can be referenced using: fbMessenger.
This identifier can be used in the rules
array, and customBody
sections.
Enable the Facebook channel
See our Messenger setup guide for more information on how to set up a channel for sending through Messenger.
Obtain a Messenger ID
There are two pieces of data that Messenger uses to match a target customer for a message:
- Messenger ID
A unique numeric identifier for a user and your Facebook page combination. - Mobile Phone Number
Use a mobile phone number in international format as long as you have enabled Customer Matching on your Facebook page.
Not all users enter a mobile number
Phone number matching for Messenger can only work if the target Facebook user has entered their mobile number into their Facebook profile.
Sending using Customer Matching
Facebook has currently suspended the use of this feature
Facebook is reviewing the ability to use phone numbers to send Messenger messages, and therefore this option is currently unavailable.
If you choose to use the customer’s phone number to identify them on Facebook, and can provide the customers first and last names, then we can automatically pass these on to Facebook with the phone number. This greatly increases the chance of Facebook matching the phone number correctly, as the name and phone number matching gives them much more confidence that you are communicating with your intended customer.
You should pass the following fields in the to
section of the send request:
Property | Type | Description |
---|---|---|
phoneNumber * | string | The international format phone number for the customer, for example, 447123123123. |
firstName | string | The first name of the customer. |
lastName | string | The last name of the customer. |
Send using a Messenger ID
To guarantee being able to send a message to a customer through Messenger you must obtain a unique Messenger ID for them and your page combination.
To do this:
- The customer elects to receive messages using the Facebook Send to Messenger plugin from a web page.
- The customer sends your Facebook page a direct message through Messenger.
- The customer clicks on the Message Us Facebook plugin and sends a message.
Use the Facebook web plugins
Facebook European country restrictions
Messenger Plugins are no longer available for use in European countries. See the following Facebook article for more information.
Facebook provides web plugins that you can add to your website to invite customers to allow you to interact with them through Messenger.
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 the user in Messenger by providing a Messenger ID for the customer through a webhook call. - Checkbox Plugin
Not currently supported.
Learn more about Facebook web plugins in Meta’s developer documentation.
Use the Send to Messenger web plugin
In order to use the Send to Messenger plugin, you can use one of the following approaches:
- Pass the profile ID of the user securely with the Send to Messenger data and we update the customer profile with their Messenger ID in the
fbMessengerId
attribute. - Capture and record the Messenger ID yourselves for use with the Enterprise Communications API.
Create secure metadata to use with the plugin
In order for us to be able to update the correct user profile with the Messenger ID received we need you to attach some secure metadata to the Facebook plugin call.
To generate this data:
- Ensure you have setup your Facebook page.
Learn how in the channel setup guide. - From your server side, call the Facebook Metadata service, passing the
profileId
you want to attach the Messenger ID to. This is usually the logged user ID. This service generates the secure metadata we can recognise. - Ensure that the secure metadata created in step 2 is passed into the Send to Messenger web control in the
data-ref
property, for example:
<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>
- Ensure that the Send to Messenger control is implemented on your website according to Meta’s instructions.
We handle the Opt-in callback from Facebook for you, so you don’t need to do this. The messenger_app_id is set to 336037380081042.
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.
Capture the Messenger ID yourself
See Meta’s developer documentation about the Facebook web plugins for further instructions on how to achieve this. You’re required to create a Facebook application and a webhook to receive the opt in data from Facebook.
Find a customer’s Facebook ID after they have opted in
We 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 customer profile in the fbMessengerId
attribute.
If we can’t find any secure metadata with a Facebook opt-in or inbound message, it automatically creates a profile for the user, so you can message them. If we do find secure metadata, we decode this and store the Facebook ID and information against the profile specified in the metadata.
In addition to storing the Facebook ID on the profile, we 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 user’s profile.
Send a Messenger message
The Enterprise Communications API allows you to address customers on Facebook using one or more of the following:
- Customer Profile ID
This is the easiest option. We 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. - Phone Number Matching
If you have enabled Customer Matching on your Facebook page you can pass a phone number in international format, but we also highly recommend passing the customers firstName and lastName to significantly increase the chance of a match. - Facebook Messenger ID
If you’ve already captured the customer’s Messenger ID for your Facebook page, you can use this.
We always use a Messenger ID in preference to the phone number or profile if included in the API call.
To test your channel you can call the Enterprise Communications 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 documentation.
Example request:
{
"to": {
"profileId": "[email protected]"
},
"body": "My customer message via Facebook Messenger using a profile id",
"rules": [
"fbMessenger"
]
}
{
"to": {
"profileId": "[email protected]"
},
"body": "My customer message via Facebook Messenger using a profile id",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "NON_PROMOTIONAL_SUBSCRIPTION"
},
"rules": [
"fbMessenger"
]
}
{
"to": {
"phoneNumber": "447123123123",
"firstName": "Dave",
"lastName": "Smith"
},
"body": "My customer message via Facebook Messenger using phone number matching",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "NON_PROMOTIONAL_SUBSCRIPTION"
},
"rules": [
"fbMessenger"
]
}
{
"to": {
"fbMessengerId": "11112223333444444"
},
"body": "My customer message via Facebook Messenger using explicit fbMessengerId",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "NON_PROMOTIONAL_SUBSCRIPTION"
},
"rules": [
"fbMessenger"
]
}
{
"title": "Your order has been dispatched",
"to": {
"profileId": "[email protected]"
},
"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": "My customer message via Facebook Messenger",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "NON_PROMOTIONAL_SUBSCRIPTION"
},
"rules": [
"fbMessenger",
"sms"
]
}
You must specify either a message tag or type for subscription messages
If you are not directly replying to an inbound message on the Messenger channel then you must specify either a
messageTag
ormessagingType
in your channel options, as Facebook consider this a subscription message.In addition to setting your message type or tag, your Facebook page must be approved for subscription messaging. Learn how to submit your page for subscription messaging in this Facebook article.
Channel options
Now required for subscription messages
If you’re 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 Messenger channel’s most common options.
To use the channel options create a object with your options in the request’s channelOptions
section in the fbMessenger
property:
Property | Type | Description |
---|---|---|
messageTag | string | Send message with one of the predefined tags specified by Facebook to increase deliverability for certain categories of messages. Learn more in the Facebook Tags documentation. |
messagingType | string | You need to specify a message type if your message is not a direct response to a customer’s inbound message, for example, it’s a notification message and you haven't specified a messageTag .You should use the message type MESSAGE_TAG for these messages to be sent, along with an appropriate messageTag , for most messages this will be NON_PROMOTIONAL_SUBSCRIPTION.Learn more about the message types you can select from in Meta’s developer documentation. Your Facebook page must request and be approved to send subscription messages. See the Messenger Platform Policy for more information on Facebook message types. |
{
"to": {
"profileId": "[email protected]"
},
"body": "The jacket you wanted is now back in stock.",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "NON_PROMOTIONAL_SUBSCRIPTION"
}
},
"rules": [
"fbMessenger"
]
}
{
"to": {
"profileId": "[email protected]"
},
"body": "Good news, your order #12345 has shipped.",
"channelOptions": {
"fbMessenger": {
"messagingType": "MESSAGE_TAG",
"messageTag": "SHIPPING_UPDATE"
}
},
"rules": [
"fbMessenger"
]
}
{
"to": {
"profileId": "[email protected]"
},
"body": "Hi, how can we help?",
"channelOptions": {
"fbMessenger": {
"messagingType": "RESPONSE"
}
},
"rules": [
"fbMessenger"
]
}
{
"to": {
"profileId": "[email protected]"
},
"body": "Thanks for contacting us; this ticket is now closed.",
"channelOptions": {
"fbMessenger": {
"messagingType": "UPDATE"
}
},
"rules": [
"fbMessenger"
]
}
Custom body
Messenger is capable of sending many types of messages including:
The Enterprise Communications 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 documentation.
Essentially, you can pass any Facebook message type you wany if you define this property, or let us automatically create you a basic text message.
Examples of sends using Facebook custom bodies:
{
"body": "Test from Comapi",
"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"
}
}
}
},
"rules": [
"fbMessenger"
]
}
{
"body": "Test from Comapi",
"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"
}
]
}
},
"rules": [
"fbMessenger"
]
}
{
"body": "Test from Comapi",
"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
}
]
}
}
}
},
"rules": [
"fbMessenger"
]
}
Receipts and inbounds
Allows you to receive Messenger messages sent from phones or Facebook to your Facebook page. Messages are delivered to a URL of your choosing using the webhook system.
If you need to to know the status of messages you've sent using one of our Enterprise Communications APIs, you can request that delivery receipts are forwarded to a URL of your choosing the webhook system.
You can receive the following types of receipts:
- Sent
- Delivered
- Read
- Failed
Check out our quick starts
Check out our Using Facebook quick start to see code examples of how to use Facebook with our API.