CSML Studio
  • Introduction
  • 🦜Getting started
    • Create Your First Bot
    • The Dashboard
    • AI & Natural Language Processing
      • AI Rules
      • Configuring a NLU Provider
    • Apps and Integrations
      • Authoring Custom Apps
      • CSML Integrations
      • Tools and utilities
      • Preprocessing
    • Livechat
      • Chatwoot
    • Bot Configuration Options
    • Authenticating Users
    • 💻CSML Language Reference
  • 🔌Studio API
    • Getting Started
    • Authentication
    • Studio CLI
    • API Reference
      • Chat API
      • Broadcasts API
      • Bot API
      • Conversations API
  • 📱Channels
    • Introduction
    • Assistant
      • Installation
      • Configuration
      • Customization
      • Widget
      • Message Formats
    • Workplace Chat
      • Installation
      • Uninstallation
      • Configuration
      • Features and message formats
    • Microsoft Teams
      • Installation
      • Features
    • Google Chat
      • Installation
      • Features
    • WhatsApp
      • Installation
      • Features and Limitations
    • Telegram
      • Installation
      • Features
    • SMS (with Twilio)
      • Installation
      • Features and Limitations
    • Slack
      • Installation
      • Message formats
      • Features
    • Callbots (with Twilio)
      • Installation
      • Features and Limitations
    • Amazon Alexa
      • Installation
    • Google Assistant
      • Installation
    • Messenger (legacy)
      • Installation
      • Configuration
      • Features
      • Message formats
    • Instagram (legacy)
      • Installation
      • Configuration
      • Features
    • Webapp (legacy)
      • Installation
      • Configuration
      • Customization
      • Chatbox
      • Message Formats
Powered by GitBook
On this page
  • Available components
  • Special behaviors
  • Thumb up event
  • Buttons and quick replies
  • Carousel
  • Raw objects
  • Broadcast
  • Limitations
  • Single Button Components
  • Fallbacks
  • Notifications
  • Event Metadata

Was this helpful?

Export as PDF
  1. Channels
  2. Messenger (legacy)

Features

PreviousConfigurationNextMessage formats

Last updated 3 years ago

Was this helpful?

Available components

Messenger channel supports all CSML components: Text, Typing, Wait, Image, Question, Button, Carousel, Card, Audio, Video, Url, File.

Special behaviors

Thumb up event

A "thumb up" button click is interpreted as a special Payload component event. CSML will receive the following data:

{
  "content_type": "payload",
  "content": { "payload": ":like:" },
}

Buttons and quick replies

Messenger differentiates between several types of buttons. Currently, CSML Studio will allow you to send either or 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:

say Question(
    "Is it:",
    buttons=[Button("a bird"), Button("a plane"), Button("Superman")],
    button_type="quick_reply"
)

Carousel

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:

do card1 = Card(
    "Classic T-Shirt",
    image_url="https://petersfancybrownhats.com/company_image.png",
    subtitle="Medium Grey",
    default_action=Url("https://zuckstees.com"),
    buttons=[Button("View Details"), Url("https://zuckstees.com", text="Shop Now")],
)
do card2 = Card(
    "Classic T-Shirt",
    image_url="https://petersfancybrownhats.com/company_image.png",
    subtitle="Midnight Blue",
    default_action=Url("https://zuckstees.com"),
    buttons=[Button("View Details"), Url("https://zuckstees.com", text="Shop Now")],
)
do card3 = Card(
    "Classic T-Shirt",
    image_url="https://petersfancybrownhats.com/company_image.png",
    subtitle="Sky Blue",
    default_action=Url("https://zuckstees.com"),
    buttons=[Button("View Details"), Url("https://zuckstees.com", text="Shop Now")],
)

say Carousel(cards=[card1, card2, card3])

Raw objects

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.

say {
  "attachment": {
    "type": "template",
    "payload": {
      "template_type": "airline_checkin",
      "intro_message": "Check-in is available now.",
      "locale": "en_US",        
      "pnr_number": "ABCDEF",
      "checkin_url": "https:\/\/www.airline.com\/check-in",  
      "flight_info": [
        {
          "flight_number": "f001",
          "departure_airport": {
            "airport_code": "SFO",
            "city": "San Francisco",
            "terminal": "T4",
            "gate": "G8"
          },
          "arrival_airport": {
            "airport_code": "SEA",
            "city": "Seattle",
            "terminal": "T4",
            "gate": "G8"
          },
          "flight_schedule": {
            "boarding_time": "2016-01-05T15:05",
            "departure_time": "2016-01-05T15:45",
            "arrival_time": "2016-01-05T17:30"
          }
        }
      ]
    }
  }
}

Broadcast

  • 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)

Failing to respect this rule may get your chatbot and/or page banned from facebook!

Limitations

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.

Single Button Components

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:

say Button("Click me!")

You should always use a Question component instead:

say Question(
    "What happens now?",
    buttons = [Button("Click me!")]
)

Fallbacks

  • 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)

Notifications

Event Metadata

A sample _metadata for an incoming event will be similar to the following object:

{
  "_channel": {
    "name": "Toto",
    "page_id": "866763783487618",
    "type": "messenger"
  },
  "first_name": "Tutu",
  "id": "3806023792815674",
  "last_name": "Tata",
  "name": "Tutu Tata",
  "gender": "male",
  "locale": "en_US",
  "timezone": 2
}

There are several types of . 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.

For example, whilst CSML does not (yet) cover Airline Templates for Messenger, you can always send a raw object if you need it:

Messenger supports , with some important caveats. You should read carefully what the limitations are on . In short:

After this 24-hours window, you must include one of the valid in your request. This is done by adding a "message_tag":"TAG_NAME" in the metadata of the request, as shown below:

Due to 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.

📱
regular
quick_reply
quick_reply buttons
Check-In Template
broadcasts
Facebook's documentation
message tags
the recent changes
Examples of quick_reply buttons. On the right, an image_url property is set.