{
  1. Introduction
    1. Prerequisites
    2. Channels
  2. Integration
    1. SDKs
    2. API endpoints
    3. Authentication
    4. Encryption
    5. Receiving messages
  3. Shared Features
    1. Sending messages
    2. Batching
    3. Channel fallback
    4. Validity period
    5. Rich content
    6. Responses & Errors
  4. SMS
    1. Unicode
    2. Multipart
  5. WhatsApp
    1. Encryption
    2. Sending messages
    3. Text message
    4. URL previews
    5. Template message
    6. Media message
    7. Location message
    8. Contact message
  6. Twitter
    1. Fact sheet
    2. Onboarding
    3. Business rules
    4. Considerations
    5. Sending messages
    6. Receiving messages
    7. Examples
  7. Facebook Messenger
    1. Fact sheet
    2. Onboarding
    3. Business rules
    4. Considerations
    5. Sending messages
    6. Receiving messages
    7. Examples
  8. Apple Business Chat
    1. Sending messages
    2. Text message
    3. URL previews
    4. Media message
    5. Suggestions
  9. RCS
  10. Viber
  11. Push
  12. Status Reports
  13. SMPP
  14. XML
  15. Http Get-requests
  16. Glossary
  17. Conversion API

Facebook Messenger

Note: for early access clients only

Our business messaging API supports sending and receiving Facebook Messenger messages.

Being able to send Facebook Messenger messages requires requesting access via the Channels portal. Without onboarding with Facebook Messenger via the portal, you can not make use of this part of the API.

Fact sheet

Feature Support Remarks
delivery notification yes Occurs when your message is delivered to the Facebook Messenger platform. Delivery notifications are sent to the status report webhooks.
text messages yes The maximum length of a Facebook Messenger message is 2.000 characters and it must be UTF-8 encoded.
media yes Media name attribute should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own Facebook Messenger message. When the linked media doesn't exist/can't be found, the message will not be sent at all. The provided text message is sent in a separate Facebook Messenger message.
media: images yes Maximum file size for an uploaded image is 25 MB. All common MIME types supported. For example: image/jpgimage/jpeg, image/png, image/webp.
media: gifs yes Maximum file size for an uploaded GIF is 25 MB. Supported MIME types are image/gif.
media: video yes Maximum file size for an uploaded video is 25 MB. All common MIME types supported. For example: video/mp4, video/quicktime.
media: audio yes Maximum file size for an uploaded audio is 25 MB. All common MIME types supported. For example: audio/aac, audio/mpeg.
media: document yes Maximum file size for an uploaded document is 25 MB. All common MIME types supported. For example: application/pdf.
reply suggestions yes Maximum label length: 20 characters.

Onboarding

Onboarding is done via our Channels portal. On our portal, you will be presented with a facebook login pop up. In this pop up you will need to authorize our Facebook app, called CM.com Business Messaging to send and receive Facebook Messenger messages on behalf of your Facebook account.

This app requires the following permissions to work correctly:

  • "Manage and access Page conversations in Messenger"
  • "Show a list of the Pages you manage"

If you choose the de-select these permissions in the facebook pop up, we will not be able to complete the onboarding.

Business rules

Sending Facebook Messenger messages using the CM Business Messaging API also requires you to adhere to the Facebook Messenger Policy & Guidelines.

It is allowed to have multiple Facebook accounts under one CM.com account.

Considerations

Note that in case of Facebook, the Facebook account that is used for sending messages is also still available in the regular Facebook app, from the Facebook website and from other 3rd party Facebook apps. Our API only has permissions to send on behalf of the Facebook account, but it's not exclusively in control of that Facebook account.

This means that it will be possible to send messages using Facebook as well as using our API, and that might lead to situations where the API will relay replies to messages you sent via the Facebook app or website.

In those cases it will seem like messages are missing from a conversation when you use both ways of communicating with your end-users.

Our recommendation is to use the API exclusively for these Facebook accounts, and not switch between the Facebook app or website and the API, because the API won't "know" about the messages you sent using the app or website, but it will receive the replies to those messages.

The only way to have a Facebook Messenger conversation with end-users is when the end-user starts the conversation by sending you an initial message.

Facebook Messenger has rate limits in place; the per day rate limit is equal to 200 * the number of people the customer can message via Facebook Messenger.

As of December 16th, 2020, Facebook will restrict the use of Facebook Messenger because of privacy rules of the European Union. In this context this means that you cannot send or receive audio, videos and attachments through Facebook Messenger. It is still possible to send and receives images.

If you choose to revoke any of the permissions given during the onboarding process on facebooks side, we might no longer be able to deliver messages.

Sending messages

Unlike other channels, Facebook Messenger does not use telephone numbers as identifiers for sender (from) and recipient (to.number), instead it uses a so called "Page Scoped User ID (PSID)" for the recipient and a "Page ID" for the sender. A person is assigned a unique PSID for each Facebook Page they start a conversation with.

These IDs are visible in the CM.com platform as the userid under channels...Facebook Messenger.

Display order

If you send a message including both an image and some text, Facebook Messenger will display these as separate messages; typically the text will be the first message.

See the Facebook Messenger message with text and image example.

Quick reply suggestions

Quick Replies allows you to suggest quick answers for the recipient beneath your message. Quick replies can be combined with any type of message; text, media or rich card. A maximum of 13 quick replies are supported by Facebook Messenger.

The following restrictions apply for a quick reply:

Field Required Remarks
label Yes Maximum length is 20 characters.
postbackdata Yes Maximum length is 1000 characters.
media No Thumbnail image, should be at least 24 x 24 pixels.

Quick replies can also be included as a reply button to a template but each template has its own button limit. If those limit has been passed, your reply suggestions will be included as quick replies beneath your message.

More info can be found in the rich content description.

Message Tags

Message tags enable sending important and personally relevant 1:1 updates to users outside the standard messaging window of 24 hours. This enables greater flexibility in how you interact with people, as well as the types of experiences you can build on the Facebook Messenger Platform. They may not be used to send promotional content (e.g. deals, offers, coupons, discounts, etc.). Use of tags outside of the approved use cases may result in restrictions on the Page's ability to send messages. See the Facebook Messenger Platform policy for details.

The following message tags are supported:

Tag Description
CONFIRMED_EVENT_UPDATE Send the user reminders or updates for an event they have registered for (e.g., RSVP'ed, purchased tickets). This tag may be used for upcoming events and events in progress.
POST_PURCHASE_UPDATE Notify the user of an update on a recent purchase.
ACCOUNT_UPDATE Notify the user of a non-recurring change to their application or account.
HUMAN_AGENT Allows human agents to respond to user inquiries. Messages can be sent within 7 days after a user message (this message tag is in closed BETA; contact Facebook to apply for access).

Rich card

Rich cards, called templates in Facebook Messenger, offer a way for you to offer a richer in-conversation experience than standard text messages by integrating buttons, images and more alongside text in a single message. Rich cards can be used for many purposes, such as displaying product information or asking the message recipient to choose from a pre-determined set of options.

You can send rich cards as one of the following Facebook templates.

  • Button template
  • Media template
  • Product template
  • Generic template

More info about the templates specifically down below.

When sending rich cards we recommend adhering to the Best Practices defined by Facebook.

Button template

The button template sends a structured message with up to three attached buttons. This template is useful for offering the recipient options to choose from, such as pre-determined responses to a question, or actions to take.

The button template is quit similar to other templates. But unlike other templates, there is a maximum of 640 characters.

The following restrictions apply for a button template:

Field Support Required Remarks
cards No No Supported if a single card is given
header Yes Yes Displayed as the text. Maximum length is 640 characters.
text No No -
mediaUri No No -
suggestions Yes Yes Maximum of 3 buttons per card. If more are given, all will be included as quick replies, instead of buttons.

The following Facebook buttons can be used. More info about each button can be found in the rich content description.

Button Action Remarks
URL OpenUrl Maximum length of button text is 20 characters, url required.
Postback Reply Maximum length of button text is 20 characters.
Call number Dial Maximum length of button text is 20 characters, phone number required.
Log in Login Button without text, url required.
Log out Logout Button without text.

When sending rich cards containing buttons, we recommend adhering the Best Practises for using buttons defined by Facebook.

Media template

The media template allows you to send a image, GIF, or video as a structured message with an optional button. Videos and animated GIFs sent with the media template are playable in the conversation.

The following restrictions apply for a media template:

Field Support Required Remarks
cards No No Supported if a single card is given
header No No -
text No No -
mediaUri Yes Yes Image or video
suggestions Yes No Maximum of 1 button per card. If more are given, all will be included as quick replies, instead of buttons.

Product template

The product template sends a structured message to render products that have been uploaded to your Facebook catalog. You need to provide the product ids that are linked to your Facebook page.

Up to 10 products can be provided via either suggestions directly or suggestions in a carousel.

The following restrictions apply for a product template:

Field Support Required Remarks
cards Yes No With a maximum of 10 per message.
header No No -
text No No -
mediaUri No No -
suggestions Yes Yes Only action 'ViewProduct' supported. With a maximum of 10 per message.

Generic template

A simple structured message that includes a title. May include a subtitle, image and up to three buttons.

This template will be used if fields are given that are not covered by other Facebook templates.

The following restrictions apply for a generic template:

Field Support Required Remarks
cards Yes Yes (If header not defined) Maximum 10 allowed per message. At least one property must be set in addition to header.
header Yes Yes (If cards not defined) Displayed as the title. Maximum length is 80 characters.
text Yes No Displayed as the subtitle. Maximum length is 80 characters.
mediaUri Yes No The URL of the image to display.
suggestions Yes No Maximum of 3 buttons per card. If more are given, all will be included as quick replies, instead of buttons.

Input matrix

You can use the following matrix to check what type of message will be send with the included inputs.

Text Media Suggestions Header Output
x x x x Not supported
x x x Generic template
x x x Product template if 'ViewProduct' action, otherwise not supported
x x Button template with buttons or quick replies
x x x Media message
x x Generic template
x x Media template with button or quick replies
x Generic template with buttons or quick replies
x x x Text message
x x Generic template
x x Text message with quick replies
x Generic template with buttons or quick replies
x x Text and Media messages
x Generic template
x Not supported
Generic template with buttons or quick replies

Receiving messages / Inbound flow

Since Facebook Messenger is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Facebook Messenger you need to set up your webhook API in the Channels app, not in the Gateway app.

Examples

Direct message with plain text contents

The example below will send a simple text-only Facebook Messenger message.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "allowedChannels": ["Facebook Messenger"],
                "body": {
                    "type": "auto",
                    "content": "CM.com - Be part of it."
                }
            }
        ]
    }
}

Direct message with text and image

In the example below we send a simple rich content message that contains both text and an image that Facebook Messenger will display as two separate messages. An explanation on how to send rich content messages in general can be found in the rich content description.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "allowedChannels": ["Facebook Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "media": {
                                "mediaName": "conversational-commerce.jpg",
                                "mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
                                "mimeType": "image/jpg"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with rich card content

In the example below we send a simple rich content message that contains elements that Facebook Messenger will display as a generic template. An explanation on how to send rich content messages in general can be found in the rich content description.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "allowedChannels": ["Facebook Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "carousel": {
                                "cards": [
                                    {
                                        "header": "CM.com - Be part of it.",
                                        "text": "Want to know more about CM.com?",
                                        "media": {
                                            "mediaName": "cm-tablet.jpg",
                                            "mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg",
                                            "mimeType": "image/jpg"
                                        },
                                        "suggestions": [
                                            {
                                                "action": "OPENURL",
                                                "label": "Visit CM.com",
                                                "url": "https://www.cm.com/"
                                            }
                                        ]
                                    }
                                ]
                            }

                        }
                    ]
                }
            }
        ]
    }
}

Direct message with reply suggestion

In the example below we send a rich content message that contains a text and some reply suggestions. An explanation on reply suggestions can be found under Suggestions/Features under Rich Content

NOTE: Facebook Messenger only supports suggestions with "action": "Reply"

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Facebook Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "Hi, what can I do for you?",
                            "suggestions": [
                                {
                                    "action": "Reply",
                                    "label": "Call me"
                                },
                                {
                                    "action": "Reply",
                                    "label": "Email me"
                                },
                                {
                                    "action": "Reply",
                                    "label": "Send me an sms"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with product suggestions

In the example below we send a rich content message that contains elements that Facebook Messenger will render as a product from your product catalog. An explanation on how to send rich content messages in general can be found in the rich content description.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Facebook Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "suggestions": [
                                {
                                    "action": "VIEWPRODUCT",
                                    "product": {
                                        "id": "FB_tshirt_001"
                                    }
                                },
                                {
                                    "action": "VIEWPRODUCT",
                                    "product": {
                                        "id": "FB_tshirt_002"
                                    }
                                },
                                {
                                    "action": "VIEWPRODUCT",
                                    "product": {
                                        "id": "FB_tshirt_003"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with message tag

In the example below we send a simple text message with a message tag "POST_PURCHASE_UPDATE" applied. This tag is used to notify the user of an update on a recent purchase.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Page ID",
                "to": [
                    {
                        "number": "Recipients PSID"
                    }
                ],
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "allowedChannels": ["Facebook Messenger"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "Dear customer, your order with id 1234xyz has been shipped.",
                            "tag": "POST_PURCHASE_UPDATE"
                        }
                    ]
                }
            }
        ]
    }
}