How to setup a Facebook Messenger channel in CSML Studio
There are several prerequisites to building a Messenger chatbot, which we will assume are already taken care of. Before we start, please make sure that you already have:
an active Facebook account
a Facebook page for your chatbot to be associated with that you are an admin of
a CSML chatbot ready to go
In CSML Studio, visit Channels > Connect new channel > Messenger. Click on Continue with Facebook to grant permissions to CSML Studio to connect bots to your chosen pages. This starts a standard Facebook login flow:
After this, simply select the page you want to link to the bot, and wait a few seconds.
Voilà! You can now search for your chatbot in Facebook Messenger (it will be listed under the page's name).
Due to new limitations by Meta, it is currently impossible to add a new Messenger channel from CSML Studio.
Messenger is one of the most popular chat platforms, with over 1.3B users worldwide. It is also one of the platforms that democratized the use of chatbots. It has a pretty broad set of APIs and allows for some very rich message templates, which gives it a nice user experience. If you are looking to build a publicly-accessible chatbot, Messenger is definitely a solution to look at!
Messenger channel supports all CSML components: Text, Typing, Wait, Image, Question, Button, Carousel, Card, Audio, Video, Url, File.
A "thumb up" button click is interpreted as a special Payload component event. CSML will receive the following data:
Messenger differentiates between several types of buttons. Currently, CSML Studio will allow you to send either regular or quick_reply buttons.
Regular buttons are larger elements, and remain on screen after the user has clicked on them. Quick replies will display just above the user input and disappear once clicked. You can also fit more quick_reply buttons (13) than regular buttons (3) per event.
To send quick_reply events, use the following syntax:
There are several types of quick_reply buttons. You can play with the type and image_url attributes. By default, quick_reply buttons are of type text. The requirements/limitations defined in Facebook's documentation apply.
Messenger provides a Carousel format which is quite interesting for some use cases. It allows for horizontal scrolling of one or several Cards, each having the ability to display an optional image and up to 3 buttons.
It is perfect as a menu for selecting what to do next!
Messenger's Carousel is a slightly specialized version of CSML's Carousel component: it has the same default parameters but additional options are available:
Some behaviors are currently unmatched with CSML components. The coverage for messenger templates will grow over time, however, please note that if you need to send a very specific template, you can always send the raw Messenger-formatted object.
For example, whilst CSML does not (yet) cover Airline Templates for Messenger, you can always send a raw Check-In Template object if you need it:
Messenger supports broadcasts, with some important caveats. You should read carefully what the limitations are on Facebook's documentation. In short:
You can send any message that you want to any user that previously sent a message to the bot in the last 24 hours
Messages must be sent exclusively to the app-scoped user ID (you can not send a broadcast using the user's email address for example)
After this 24-hours window, you must include one of the valid message tags in your request. This is done by adding a "message_tag":"TAG_NAME" in the metadata of the request, as shown below:
Failing to respect this rule may get your chatbot and/or page banned from facebook!
In general, all Messenger limitations apply. For example, texts can not be larger than 2000 UTF-8 characters, and attachment sizes (Videos, Audio, Files) can not be larger than 25MB.
Regular buttons are limited to 3 per single event, while quick_reply buttons allow up to 13 buttons. The length of the button title should also never be longer than 20 characters.
Messenger requires buttons to have an accompanying text. The following CSML code will display an error message in the conversation, as a Button can not be used alone:
You should always use a Question component instead:
Files that are larger than 25MB will be sent as simple text instead of uploaded as attachments
Nice URLs are unavailable. They will display as simple text instead
Youtube/Dailymotion/Vimeo videos as well as Spotify/Deezer/Soundcloud audios will display as simple text
URL Buttons are currently unsupported natively (use raw objects for now)
Due to the recent changes in the way Messenger handles sending notifications to your users, CSML Studio does not allow sending messages to users except for the regular use case of responding directly to a request the user made (by sending a text message, clicking a button, etc.). To send one-way notifications (or broadcasts) to your users, you need to build your own separate logic.
A sample _metadata for an incoming event will be similar to the following object:
The Messenger channel on CSML Studio offers some configuration options. More will be added over time!
When a user starts using your bot, the first thing they will see is a Get Started button (the text will be automatically translated in their own configured language and can not be changed). In the background, a "GET_STARTED" payload is sent to the bot.
This setting helps you configure which flow will be triggered by this specific payload. By default it will be the bot's default flow, but you might want to have a different behavior for what happens when users connect to your bot for the very first time (or when they have deleted the conversation before and want to start anew).
To configure a welcome flow, simply select it in the dropdown list the flow you want to run when the user clicks on the Get Started button.
If the user has never used your bot before (or has deleted their conversation), they will be shown the default Get Started button but when they click on it, they will reach the target flow instead of the welcome flow
If the user has already used the bot, they will directly go to the defined flow, in place of where they were before.
If a user uses a link with a Ref parameter that is not configured properly, the regular behaviour will persist (the Get Started button will redirect to the welcome flow, and existing conversations will simply continue).
There are two ways to use Ref parameters to redirect to flows. You can either configure them in the channel's settings page by adding connections between custom Ref parameters and a target flow:
Or you can use the following special syntax:
The main advantage of the second syntax is that you can generate the links on the go; however, the first method is more flexible as you can easily change where a link is redirected even after it is created, and the content of the Ref parameter is entirely customizable.
We offer a simple way to set precisely the persistent menu you want, by letting you add a JSON-formatted payload to set as the bot's persistent menu. Any valid persistent menu configuration is accepted.
This is not really a configuration option, but know that the _metadata object inside your flows will contain some info about your user: their name, first_name, and last_name will be accessible in the conversation's metadata, unless they are not correctly set in their profile.
Obviously, Wait is also supported (it simply does not display a typing indicator or anything for the given duration).
Both Button() and Url() button types are supported:
you can have a maximum of 3 buttons, but up to 13 quick_reply buttons
quick_reply buttons go away once the user clicks on one or says something, regular buttons stay forever
quick_reply buttons do not support Url() types
Messenger does not support a rendering a singleButton component by itself. You must use buttons as part of Question or Card components.
The media components behave exactly as the Attachment Upload API does in Messenger, with the same limitations.
If for some reason, we are unable to send a file, it will fallback to a simple Url component. For this reason, third-party media players will be rendered as simple links to those players, while raw media can show as a regular file/audio/video/image in the conversation.
The main limitations to know about are:
file must be publicly accessible (not behind firewall, not requiring any authentication)
file must be < 25MB in size
file must be able to upload to messenger in a reasonable amount of time
Send the given URL in a simple text component.
If a text parameter is present, it will be ignored, as Messenger is unable to display hyperlinks. The raw URL will always be used.
To display a nice URL, wrap it as a button to a Question or Card component.
A Carousel is essentially a collection of Card elements A single Card will display as a Carousel of 1 element.
The Card component on Messenger supports up to 3 Button or Url buttons. You can also define an optional default_action with a Url component on each card to make the card itself clickable.
You can use to directly send users to various sections of your chatbot instead of the standard Welcome Flow. There are two scenarios:
Messenger makes it possible to add a to your bots.
There is also an id field, however this is not the user's real ID but is called an . It can not be related back to the user's actual Facebook ID.
Markdown support is scarce for Messenger, and various clients may render it differently. , text formatting is only visible on a computer, and will not appear in the Messenger app on mobile.
You can also take advantage of Facebook's "" buttons. Here they are shown with a given payload (which would also work on the above example). There are 2 main differences between regular buttons and quick_replies:
You can send any valid message as per Messenger's Send API as a raw object. For instance, taking without any modification:
For a complete reference of all the code presented on this page, refer to the :
