Facebook

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.

Enabling the Facebook Channel

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

Obtaining a Facebook Messenger Id

There are two pieces of data that Facebook Messenger uses to match a target customer for a message and they are:

• Facebook Messenger Id - A unique numeric identifier for a Facebook 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 Facebook users enter a mobile number

Phone number matching for Facebook Messenger can only work if the target Facebook user has entered their mobile number into their Facebook profile.

Sending using Customer Matching (Phone number matching)

❗️

Facebook has currently suspended the use of this feature

Facebook is reviewing the ability to use phone numbers to send Facebook Messenger messages, and therefore this option is currently unavailable.

If you choose to use the customers phone number to identify them on Facebook and can provide the customers first and last names then Comapi will 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:

Sending using a Facebook Messenger Id

To guarantee being 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 Comapi 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 Comapi 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 Comapi Enterprise Communications API

Using the Send to Messenger web plugin with Comapi

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

Create secure meta data to use with the plugin

In order for Comapi 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 Comapi 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 Comapi 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 Comapi 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 Comapi's app id 336037380081042
• Your Facebook page has been configured in the Comapi 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?

Comapi 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 Comapi profile in the fbMessengerId attribute.

If Comapi 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 Comapi 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 Comapi One API allows you to address customers on Facebook using one or more of the following:

• Customer Profile Id - This is the easiest option, Comapi 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
• Phone Number Matching - If you have enabled Customer Matching on your Facebook page simply pass a phone number in international format, but we also highly recommend passing the customers firstName and lastName to increase the chance of a match significantly!
• Facebook Messenger Id - If you have already captured the customers Facebook Messenger Id for your Facebook page you can use this

Comapi will always use a Facebook Messenger Id in preference to the phone number or profile if included in the API call.

To test your channel you can call the Comapi 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 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": "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 Facebook Messenger channel then you will need to 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. To submit your page for subscription messaging approval please follow these instructions.

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

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

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

The Comapi 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 docs. Essentially you can pass any Facebook message type you desire if you define this property, or let Comapi automatically create you a basic text message.

Examples of sends using Facebook custom bodies are:

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

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 Comapi's 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 Enterprise Communications API, you can request that delivery receipts are forwarded to a URL of your choosing using Comapi's 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

👍

Check out our quick starts...

Check out our Using Facebook quick start to see a simple code example of how to use Facebook with Comapi