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:

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:

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 through Messenger.
3. The customer clicks on the Message Us Facebook plugin and sends a message.

Use the Facebook web plugins

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

Learn more about Facebook web plugins in Meta’s developer documentation.

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 or messagingType 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:

{
  "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:

• Text
• Attachments
• Quick replies
• Buttons
• Templates

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

Inbound messages

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.

Receipts

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.