CSML provides a way to execute external code in any language of your choice via a Foreign Function Interface, represented by the App() keyword.

Here are some ideas for CSML integrations:

• file tickets to Zendesk, ServiceNow or Front

• create leads in Hubspot, Mailchimp, Salesforce

• store data on Airtable, Google Sheet, Amazon DynamoDB

• upload files to Box, Google Docs, Office 365

• analyze text with SAP Conversational AI, Dialogflow, Rasa

• book meetings on Google Calendar, Hubspot, Calendly

• trigger events in Zapier, IFTTT, Integromat

• generate QR codes, format documents, upload images...

• and many more!

There are 2 ways you can augment your CSML chatbot by connecting it to other services: authoring your own custom apps, or installing ready-to-use CSML Integrations.

Introduction

In this tutorial, you will learn how to setup a chatbot that will qualify leads and sign them up to your Mailchimp contact list.

At the end of this tutorial, here is what you will be able to:

• Get information from the end-user

• Subscribe this user to an existing Mailchimp contact list

• Ask users for feedback on their experience, and send a custom answer based on their response

Writing your CSML flow

A CSML flow always starts in the start step, in this step, we introduce the chatbot. Note that Typing(2000) needs to be preceded by the say keyword, this will show the three little jumping dots on the screen, suggesting the chatbot is typing, this action will last 2 seconds (2000 milliseconds).

start:
    say Typing(2000)
    say "Hi 🤓, I just need a few informations in order to add you to my mailing list."
    goto firstname

We can then move on to the next step in which we will start asking for user informations.

Asking questions and remembering answers

With CSML, in order to wait for the user to reply to a question (or anything else for that matter), we use the keyword hold, the chatbot then waits for the user to reply. After answering, the user input will be placed in the event variable.

Note: the event variable is scoped to the current step, which basically means that event will be wiped off the memory once the chatbot goes out of the current step.

In order to remember what the user said, we can ask the chat to remember nlFirstname = event, and nlFirstname will then be accessible anywhere, anytime.

firstname:
    say Typing(2000)
    say "What's your firstname?"
    hold

    remember nlFirstname = event 
    goto lastname

Let's move to the next step : lastname

First let's have a look at the Button(...) component: it has two parameters, a title="" that represents what will be displayed inside the button, and an accept=[] parameter that is a list of all the words that correspond to this button. This way, if a user types "NA", CSML will understand it as being the same as a click on this button. Lastly, we set this button as variable btnLastname.

Now that our button is saved, we then create a Question component, add the preset button and hold.

As the user answers, we check if the input matches the button or what it accepts ans remember the appropriate nlLastname.

lastname:
    say Typing(2000)
    do btnLastname = Button(
        title = "I don't want to share my lastname",
        accept = ["No", "No", "no", "NA", "N/A", "na", "n/a"]
    )

    say Question(title="What's your lastname?", buttons=[btnLastname])
    hold

    if (event.match(btnLastname)) remember nlLastname = "N/A"
    else remember nlLastname = event
    goto email

The same goes with the email, only this time we're checking if the user input contains a @, if it doesn't we start the step again, otherwise we remember the email and move on to save everything.

email:
    say Typing(2000)
    say "What's your email address?"
    hold

    // does the user's input look like an email address?
    if (event.is_email()) {
        remember nlEmail = event
        goto save
    }

    // otherwise the input is probably not a valid email address
    // we need to ask them again
    say "That's not a valid email address 😱"
    goto email

Sending data to Mailchimp

Thanks to our apps directory, you can install the Mailchimp app in a few clicks (you'll just need to get your API Region, API key and contact list ID). The app needs an option parameter that encloses all the informations that Mailchimp needs.

Note that App(...) needs to be used in a do statement.

save:
    // prepare the arguments required by the mailchimp app
    do options = {
        "listId": "d8acdcc85f",
        "email": nlEmail,
        "firstname": nlFirstname,
        "lastname": nlLastname,
    }
    // execute the app
    do mailchimpResponse = App("mailchimp", action="subscribeToList", options=options)

    say Typing(2000)
    say "I have added you to our newsletter subscription list !"

    goto feedback

Now it's time to get some feedback from the user!

NLP coming into play

We want to use the SAP Conversational AI to find out if the user's input is positive, neutral or negative. The API returns this as sentiments. If you want to see the full response from the API, you can print it using say "{{sapcaiResponse}}"

feedback:
    say "How did you like this newsletter onboarding?"
    hold

    // query the NLP service
    do sapcaiResponse = App("sap/cai", text=event)

    // this contains the sentiment analysis of the query
    say sapcaiResponse.results.sentiment

    if (Find("positive", in=sapcaiResponse.results.sentiment)) {
        say "Thank you so much for your kind words 😇."
    } 
    else if (Find("negative", in=sapcaiResponse.results.sentiment)) {
        say "I'd love to know what went wrong, please join our slack channel and let us know."
    } 
    else {
        say "I am sure you'll get to love CSML :D"
    }

    goto end

That's it !

You've done it, you've created your first CSML bot from scratch ! Here is the full code:

start:
    say Typing(2000)
    say "Hi 🤓, I just need a few informations in order to add you to my mailing list."
    goto firstname


firstname:
    say Typing(2000)
    say "What's your firstname?"
    hold

    remember nlFirstname = event 
    goto lastname


lastname:
    say Typing(2000)
    do btnLastname = Button(
        title = "I don't want to share my lastname",
        accept = ["No", "No", "no", "NA", "N/A", "na", "n/a"]
    )

    say Question(title="What's your lastname?", buttons=[btnLastname])
    hold

    if (event.match(btnLastname)) remember nlLastname = "N/A"
    else remember nlLastname = event
    goto email


email:
    say Typing(2000)
    say "What's your email address?"
    hold

    // does the user's input look like an email address?
    if (event.is_email() {
        remember nlEmail = event
        goto save
    }

    // otherwise the input is probably not a valid email address
    // we need to ask them again
    say "That's not a valid email address 😱"
    goto email


feedback:
    say "How did you like this newsletter onboarding?"
    hold

    // query the NLP service
    do sapcaiResponse = App("sap/cai", text=event)

    // this contains the sentiment analysis of the query
    say sapcaiResponse.results.sentiment

    if (Find("positive", in=sapcaiResponse.results.sentiment)) {
        say "Thank you so much for your kind words 😇."
    } 
    else if (Find("negative", in=sapcaiResponse.results.sentiment)) {
        say "I'd love to know what went wrong, please join our slack channel and let us know."
    } 
    else {
        say "I am sure you'll get to love CSML :D"
    }

    goto end


save:
    // prepare the arguments required by the mailchimp app
    do options = {
        "listId": "d8acdcc85f",
        "email": nlEmail,
        "firstname": nlFirstname,
        "lastname": nlLastname,
    }
    // execute the app
    do mailchimpResponse = App("mailchimp", action="subscribeToList", options=options)

    say Typing(2000)
    say "I have added you to our newsletter subscription list !"

    goto feedback

If you have any question, please come ask us on Slack!

CSML Studio allows you to use your own pre-trained Natural Language Processing (NLP) service directly in your CSML chatbots with very little configuration. You can easily setup your favorite NLP provider in AI & NLU > NLU Configuration:

By default, all bots run in Strict Mode, where the input needs to exactly match one of the given rules to trigger a flow.

When a NLP provider is configured, all text events will be sent to the NLP provider and returned either as a payload event if an intent is found, or untouched if no intent is found. When an intent is found, the value of the payload will be intent:nameOfIntent.

No matter what NLP provider you pick, any event that passes through this process will have the following properties:

// if an intent is found:
event.intent = {
  "name": "..." // contains the name of the intent, same
  "confidence": "..." // the confidence score that this is the right intent
}

// or, when no intent is found:
event.intent == null

// if other intents match the request:
event.alternative_intents = [ Intent {}, ... ]

// when entities are found, event.entities containes a map of found entities
event.entities.ENTITY_NAME = [
  {
    "value": "the value",
    "metadata": {
      // ... additional metadata as returned by the NLP provider
    }
  }
]

// when this information is known, the processing language code
event.language = "en"

A few additional properties are also set in the resulting event:

• event._nlp_provider: contains details about the NLP provider integration

• event._nlp_result: contains the raw response from the NLP provider

• event.text: contains the original text input

Using NLU in your flows

You can now use the event by matching a found intent with a flow command, by setting that intent as one of the accepted commands for a flow, using the AI Rules feature.

Alternatively, you can also decide to match buttons or other actions within a flow with the found data. For instance, you can use NLP to detect a YES_INTENT and match it without having to list all the possible ways to say "yes" in the button's accepts array.

start:

  say Question(
    "Do you like chocolate?",
    buttons=[
      Button("Yes", accepts=["intent:YES_INTENT"]) as btny,
      Button("No", accepts=["intent:NO_INTENT"]) as btnn,
    ]
  )
  hold
  
  if (event.match(btny)) say "I knew it!"
  else if (event.match(btnn)) say "I think you are lying..."
  
  goto end

Authentication

All API calls are authenticated with the combination of two separate keys: API Key and API Secret.

The API Key is the public key and can be put in clear client-side (your website, your app...). The API Secret should never be shared publicly and should only be set on your server.

There are two different modes of authentication for Studio endpoints: Private or Public.

Public Endpoints Authentication

Public Endpoints (consisting of Chat and Broadcasts API endpoints) can be authentified by providing only the value of the Api Key in the X-Api-Key header. They can be accessed from the frontend, i.e by creating your own chat interface integrated in your app or website.

Implementation examples

When calling Chat and Broadcasts API endpoints, you only need to set the X-Api-Key header as follows:

curl -X "POST" "https://API_ENDPOINT" \
     -H 'content-type: application/json' \
     -H 'X-Api-Key: YOUR_API_KEY' \
     -d $'YOUR_REQUEST_BODY'

Private Endpoints Authentication

Private Endpoints are endpoints that should only be accessible to the developer of the chabot, allowing to modify the chatbot in its entirety or access conversation data (Bot and Conversations API endpoints). To authentify your Private Endpoints requests you need to set the X-Api-Key and X-Api-Signature headers. The CSML Studio Private APIs use HMAC authentication to ensure that all calls are properly signed with both the API Key and API Secret, while preventing man-in-the-middle attacks and replay attacks

In the X-Api-Key header, concatenate the API Key and the current unix timestamp (in seconds), separated by the | character. In the X-Api-Signature header, provide the hexadecimal sha-256 hash of the X-Api-Key header value, signed with your API Secret.

The CSML server will be able to validate that both the API Key and the API Secret used are valid, without requiring you to provide the API Secret in clear text. Replay attacks are prevented by invalidating all calls a few minutes after the timestamp provided in the X-Api-Key header.

Implementation examples

To authenticate your Private calls, you need to calculate the signature based on the Api Key and the Api Secret that you can find in CSML Studio, as well as the current timestamp. Here are implementation examples of the X-Api-Key and X-Api-Signature headers in Node.js and Python.

NB: this calculation should never be performed client-side!

const crypto = require('crypto');

const UNIX_TIMESTAMP = Math.floor(Date.now() / 1000);

const XApiKey = `${API_KEY}|${UNIX_TIMESTAMP}`;
const signature = crypto.createHmac('sha256', secret)
  .update(XApiKey, 'utf-8')
  .digest('hex');
const XApiSignature = `sha256=${signature}`;

import time
import hmac
import hashlib

timestamp = str(int(time.time()))
x_api_key = ${API_KEY} + "|" + timestamp

signature = hmac.new(
    str.encode(${API_SECRET}),
    x_api_key.encode('utf8'),
    digestmod=hashlib.sha256
  ).hexdigest()
x_api_signature = "sha256=" + signature

Then, perform an authenticated call as follows:

curl -X "POST" "https://API_ENDPOINT" \
     -H 'content-type: application/json' \
     -H 'X-Api-Key: YOUR_API_KEY_AND_TIMESTAMP' \
     -H 'X-Api-Signature: YOUR_CALCULATED_API_SIGNATURE' \
     -d $'YOUR_REQUEST_BODY'

CSML Studio comes with a CLI (command-line interface) tool that helps you develop your chatbot locally before deploying it. With the CSML Studio CLI, you can update your flows using your favorite code editor on your local machine and publish it on CSML Studio. For larger projects, we recommend using the CSML Studio CLI over the online interface as it makes it easier to manage many flows.

Setting up CSML Studio CLI

To setup CSML Studio CLI, simply install the tool with npm install -g @csml/studio-cli (requires nodejs 12+). Then, using your bot's API keys (see the Studio API section to learn more about creating API keys), you can now run csml-studio init -k MYKEY -s MYSECRET -p path/to/project.

This command will setup a local development environment where you will be able to manage your chatbot entirely from the comfort of your machine!

Broadcasting with CSML Studio CLI

Broadcasting to a large number of targets can be done really easily with the CSML Studio CLI tool. Indeed, you simply need to prepare a file with all your targets:

user1@gmail.com
someperson@hotmail.com
mydude@caramail.fr
angela@gmx.de

Then, simply run the following command, which will send each of these targets a broadcast (message initiated from the bot) on the configured channel (based on the given API keys):

csml-studio broadcast -i myfile.csv --flow_id myBroadcastFlow -k MYKEY -s MYSECRET

Source code and package repository

• github

• npm

In CSML Studio, every channel generates a set of API keys that you can use to perform various operations, such as managing the bot, sending broadcasts, getting information about current conversations... Channels are external connectors to your bot.

Every channel has different capabilities but all channels rely on the same API methods.

Endpoints

All calls are to be made to https://clients.csml.dev.

The API is versioned, and all calls must be prefixed by their version number. The most recent version is v1. The API is reachable on route prefix /api.

Hence, the complete endpoint for the API is https://clients.csml.dev/v1/api.

Throttling

To ensure the stability of downstream systems, API requests are throttled. Each client (a set of API key/secret) can only send up to 50 reqs/sec. Over this limit, an error code is returned and the request will not be treated.

Webhook

On the API channel exclusively, you can also register a webhook, which will be called with a POST request every time a message is sent by the bot to the end user. This is a good way to handle the outgoing messages in real time! The body of the webhook call is documented here.

Using SaaS providers

CSML Studio currently supports the following NLP providers:

• Dialogflow (read our blog post)

• SAP Conversational AI (formerly Recast.ai)

• Amazon Lex

• Microsoft LUIS

• Rasa

• Wit.ai

• IBM Watson

• Custom Webhook

Please refer to each provider's documentation for more information on how to generate credentials. CSML Studio supports the most common and secure way of connecting to these providers.

If your favorite provider is not in this list, please reach out to contact@csml.dev.

Using the Custom Webhook integration

You can also add a custom NLP engine by using the custom Webhook integration. This is especially useful if we don't currently support your NLP provider of choice or if you are running your NLP services on premise.

To use the Webhook integration, simply provide a URL that we can send a POST request to, with the following body:

{
  "text": "TEXT_TO_ANALYZE"
}

The URL may contain query parameters, for example with an API Key for authentication purposes.

When called, this endpoint must return the response in the following form:

{
  // intent can also be null if no intent is found
  "intent": { 
    "name": "NAME_OF_INTENT", 
    "confidence": 0.84
  },
  "alternative_intents": [ 
    // ... other matching intents
  ],
  "entities": {
    "someEntity": [
      {
        "value": "somevalue",
        "metadata": { 
          // ... any additional information about entity
        },
      },
      // ... other values for the same entity
    ],
    // ... other entities
  }
  // ... any additional data: sentiment analyzis, language...
}

You can test this endpoint directly on the configuration page.

POST /conversations/open

Find out whether a user currently has an open conversation on the current channel.

Request example

curl -X "POST" "https://clients.csml.dev/v1/api/conversations/open" \
     -H 'content-type: application/json' \
     -H 'accept: application/json' \
     -H 'x-api-key: ${X-API-KEY}' \
     -H 'x-api-signature: ${X-API-SIGNATURE}' \
     -d $'{
          "user_id": "some-user-id"
        }'

Response example

{
  "has_open": true,
  "conversation": {
    "id": "43d5939f-4afc-4953-9e53-4c28b33cedd8",
    "client": {
      "channel_id": "dd446008-3768-41df-9be9-f6ea0371f920",
      "user_id": "some-user-id",
      "bot_id": "b797a3b6-ad8c-446c-acfe-dfcafd787f4e"
    },
    "flow_id": "31c2c4b0-05d6-44ce-9442-e87e9ae7e8a2",
    "step_id": "start",
    "metadata": {
      "somekey": "somevalue",
    },
    "status": "OPEN",
    "last_interaction_at": "2019-11-16T19:57:42.219Z",
    "created_at": "2019-11-16T19:57:42.219Z"
  }
}

Get bot

GET https://clients.csml.dev/v1/api/bot

Retrieve the bot for this integration

{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "env": {
    "MY_VAR": "somevalue"
  },
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}

Update bot

PUT https://clients.csml.dev/v1/api/bot

Update a bot's name, default_flow and/or description. Parameters that are not set will not be changed.

Request Body

{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}

Get bot flows

GET https://clients.csml.dev/v1/api/bot/flows

Retrieve all the flows in the current bot

[
  {
    "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
    "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
    "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
    "name": "Default",
    "description": "Default custom flow",
    "commands": [
      "/default"
    ],
    "content": "start:\n\tsay \"hello!\"\n\tgoto end",
    "created_at": "2019-12-11T18:59:39.610Z",
    "updated_at": "2019-12-13T01:31:51.507Z",
  },
  ...
]

Create Flow

POST https://clients.csml.dev/v1/api/bot/flows

Add a new flow to the current bot

Request Body

{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 

Get flow

GET https://clients/csml.dev/v1/api/bot/flows/:flow_id

Path Parameters

{
  "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "Default",
  "description": "Default custom flow",
  "commands": [
    "/default"
  ],
  "content": "start:\n\tsay \"hello!\"\n\tgoto end",
  "created_at": "2019-12-11T18:59:39.610Z",
  "updated_at": "2019-12-13T01:31:51.507Z",
}

Update flow

PUT https://clients/csml.dev/v1/api/bot/flows/:flow_id

Path Parameters

Request Body

{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 

Bot usage

GET https://clients.csml.dev/v1/api/bot/usage

Get usage information about a bot

{
  "currentmonth": {
    "messages": 0,
    "clients": 0
  },
  "last30d": {
    "messages": 0,
    "clients": 0
  },
  "lastmonth": {
    "messages": 0,
    "clients": 0
  }
}

Validate bot

POST https://clients.csml.dev/v1/api/bot/validate

Validate bot data against the CSML interpreter

Request Body

// bot is valid
{
  "valid": true
}

// bot is invalid
{
  "valid": false,
  "errors": [
    {
      "flow": "someFlow",
      "step": "someStep",
      "line": 0,
      "column": 0,
      "message": "error message"
    }
  ]
}

Build bot

POST https://clients.csml.dev/v1/api/bot/build

Build a new version of the bot

{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}

Get bot build version

GET https://clients.csml.dev/v1/api/bot/build

Query Parameters

{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}

To make it really easy to publish your chatbot, CSML studio provides a full-featured web-based Conversational Assistant that you can easily integrate into any existing project. This is the simplest way to deploy your chatbot at scale!

Microsoft Teams is a popular channel for enterprise and team use. It allows a diversity of rich messages (images, buttons, carousels...) and is widely used in many of companies worldwide. Chatbots for Microsoft Teams benefit from a rich user experience, although setting up a bot for Microsoft Teams is a slightly complex task.

Whatsapp is one of the most used messaging platforms in the world, replacing SMS in many cases. Setting up a Whatsapp channel is slightly more complex than some other channels but it can be a great way to get in touch with your audience!

Amazon Alexa is one of the main platforms for launching Voice Bots. Using CSML Studio, you can easily deploy powerful Alexa Skills on any Alexa-activated device in the world. Let's try and walk you through your journey as a CSML Voice Bot developer!

CSML Studio supports Slack as one of its channels. Slack is a very popular option at startups and schools, and is widely used as a "ChatOps" solution by tech teams.

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!

If you already have custom code that you would like to use in your chatbot, you can import it directly as a custom app in CSML Studio and use it without any change.

In CSML Studio, apps are run by default on AWS Lambda, which ensures maximum availability, scalability and security by isolating your code in separate containers. The supported runtimes are currently:

• Nodejs v10.x and 12.x

• Java 8 and 11

• Python 2.7, 3.6, 3.7 and 3.8

• Dotnetcore 2.1 and 3.1

• Go 1.x

• Ruby 2.5 and 2.7

To get started with AWS Lambda compatible deployment package in any language, you can refer to this documentation.

Quick Mode

The easiest way to author custom apps in CSML Studio is to use the Quick Mode, which provides you with a code editor to create your app directly in the browser. There are several limitations:

• only nodejs is supported (support for python will be added shortly)

• quick apps can not contain more than 4096 characters

• custom modules can not be added (however all native node modules are supported)

• environment variables can not be configured

If you need more configuration options (other languages, bigger package size, custom modules), we recommend using the Complete Mode as explained below.

As an example, let's create a simple nodejs 12.x app that will return a random user from RandomUser.me. This code performs a simple GET request to https://randomuser.me/api and returns the first user in the returned array. The code is available here on github: download it or clone it to get started.

The App Code

To test this program, simply run node test.js at the root of the project. You should see something like the following:

Authoring in Quick Mode

Select Add Custom App at the top-right corner of the apps page, which brings you directly to Quick Mode (nodejs). Simply copy-paste the content of index.js into the code editor, choose a name for your app, then click Save.

You can now use your app in your CSML Chatbot, like this:

start:
  do user = App("getRandomUser")
  say "The random user's name is: {{user.name.first}} {{user.name.last}}"
  goto end 

Complete Mode

With complete mode, a few extra steps are needed, as you will need to provide the code in a deployment package and upload it on the platform.

Creating a deployment package

At the root of the project as downloaded from github, run the command zip -r9 ../randomuser.zip .. This will create a deployment package for your app, that you will be able to import in CSML Studio.

Uploading to CSML Studio

In the sidebar, click on Apps > Add a new app. In the app creation page, upload your deployment package, give your app a distinctive and unique name such as getRandomUser, leave index.handler as your app's main handler and select nodejs12.x as the runtime.

You can leave the sections below as is for now; if your app took any argument or required any environment variable, this is where you would configure it.

Once you are done, simply save. You can now use your app in your CSML Chatbot as above.

Good practices

• As in every development project, apps have a processing cost associated to them. The more difficult the task is, the longer it takes to perform, the worse your user experience will be. Keep in mind that running apps will also increase the latency between the user's input and the bot's response. If possible, try to stick to native CSML code!

• It is always a good practice to only return what you intend to use. For example, if you are interfacing with a product catalog, do you need to get all 3542 items in the catalog, or will the first 5 suffice? If you are retrieving a list of items, what properties from that list do you actually need?

• Apps are limited to 30s of execution time. If it takes longer, the app will stop and return an error.

• Apps only get 512MB of RAM by default. Any excessive resource usage will lead the app to stop its execution immediately.

• If you are saving the output of your app to a do x = App(..) (or a remember), the data is subject to the usual memory size limitations. In general, if your app returns more than a few KB of data, ask yourself if you really need all that data that you most likely won't be able to display in a chatbot (text-based, so really light) or if you shouldn't strip it down directly in the app itself!

CSML Studio also offers a way to preprocess every incoming event of certain types, in order to add some metadata or transform it. Here are some use cases:

• transcribe audio inputs

• translate incoming text

• save uploaded files to a dedicated file storage

• perform OCR on each uploaded image

• run a custom natural language processing library on text inputs (for that use case, you may also want to look at Natural Language Processing)

Preprocessors are simply external apps that are run on every incoming event (of the given type) and return a valid CSML event. The only specificity is that the parameters it must accept and return are standard CSML event payloads. Preprocessors that fail to accept or return such payloads are simply ignored and your incoming event will not be transformed.

How to add a CSML preprocessor

Let's create a simple Text preprocessor that will return a picture of a hot dog if the user had the word "hot dog" in their input, or change the text to "Not hot dog" otherwise.

To add a preprocessor, you first need to add a preprocessor-compatible app under the apps section (see here). For this tutorial, let's just use the Quick Mode, but of course you can use Complete Mode as well.

This is the code we are going to use:

exports.handler = async (event) => {

  const text = event.content.text;

  if (text.toLowerCase().includes('hot dog')) {
    return {
      content_type: 'image',
      content: {
P        url: 'https://media.istockphoto.com/photos/hot-dog-on-white-picture-id1130731707',
        _original_event: event,
      },
    };
  }

  return {
    content_type: 'text',
    content: {
      text: 'Not hot dog!',
      _original_event: event,
    },
  };

};

It is really simple: if the user text input contains the words "hot dog" anywhere, then return an image of a hotdog. Otherwise, change the text to "Not hot dog". In both cases, the original, untransformed event is still accessible with event._original_event in you CSML code, if needed.

Next, go to Apps > Add Custom App and under Quick Mode, simply copy and paste it, select a name for your app (for instance, hotdog seems like a fitting name), and click save.

Then, head to the Preprocessing page. We only want to preprocess text events, but of course, we could do a similar app for other types of events.

Now, back to the CSML Editor, you can do something like the following:

start:
  if (event.get_type() == "image") say Image(event)
  else say event
  goto end

The Chat API allows you to send chat requests to your bot on behalf of an end user. You can send a text request, and receive the bot's response in return.

This API works synchronously by default: you will receive all of the bot's messages in one array in response to your request.

POST /chat

You can query the Chat API by sending a simple text message for analysis. This will either continue any previous conversation or start a new one.

# replace the x-api-key and x-api-signature values with your data
curl -X "POST" "https://clients.csml.dev/v1/api/chat" \
     -H 'content-type: application/json' \
     -H 'accept: application/json' \
     -H 'x-api-key: ${API_KEY}' \
     -d $'{
            "client": {
              "user_id": "some-user-id"
            },
            "metadata": {
              "firstname": "John",
              "lastname": "Doe"
            },
            "request_id": "random-id",
            "payload": {
              "content": {
                "text": "Hello"
              },
              "content_type": "text"
            }
          }'

Valid request message payloads

The following message types are accepted (see below for payload examples): text, image, video, audio, file, url, payload, flow_trigger.

Additional properties can be added to the message's content and will be available as event.my_added_prop in the context of the CSML.

Triggering a specific flow

To trigger a specific flow, you can send the following event:

{
  "client": {
    "user_id": "some-user-id"
  },
  "metadata": {
    "key": "value",
    "otherkey": "othervalue"
  },
  "request_id": "random-id",
  "payload": {
    "content": {
      "flow_id": "some-flow-id",
      "close_flows": true
    },
    "content_type": "flow_trigger"
  }
}

You can also choose to force-close any previously open conversation with close_flows. If you don't close previous conversations and the flow is a recursive flow (i.e has no hold keywords), then the previous conversation will be relaunched at the last available step in that flow.

Request body

{
  "client": {
    "user_id": "some-user-id"
  },
  "metadata": {
    "key": "value",
    "otherkey": "othervalue"
  },
  "request_id": "random-id",
  "payload": {
    "content": {
      "text": "Hello"
    },
    "content_type": "text"
  }
}

Response body

{
  "request_id": "045338c4-f214-4f94-b1a7-3255b3d70f3c",
  "messages": [
    {
      "conversation_id": "f2461d23-6069-4f78-ae81-f127e4c3d9a0",
      "direction": "SEND",
      "interaction_order": 0,
      "payload": {
        "content": {
          "text": "Some message"
        },
        "content_type": "text"
      }
    }
  ],
  "client": {
    "bot_id": "b797a3b6-ad8c-446c-acfe-dfcafd787f4e",
    "channel_id": "dd446008-3768-41df-9be9-f6ea0371f920",
    "user_id": "some-user-id"
  },
  "received_at": "2019-11-16T17:48:26.519Z"
}

The Assistant channel also comes with a configurable website plugin (called the Widget) that can be added to any website by adding a single line in your source code. The Widget will then appear as a small bubble in the bottom-right corner of your site for every visitor.

Installation

Simply add the following line of code in your source code, just before the closing </body> tag (replace it with the actual line that you can find in your Webapp configuration panel):

<script
  src="https://widget.csml.dev/script.min.js?token=ASSISTANT_TOKEN"
  id="clevy-widget"
  async>
</script>

Once this is done, a chat bubble will appear as follows on every page where that code is included.

Adding a Custom Greeting

The Widget lets you configure a custom popup message to help you engage more actively with your customers. You can even have default greeting messages depending on the page where the widget is loaded! Here is how it works:

• Greetings are matched with their page based on the URI. The first message that matches the URI is the one that will be displayed. We support wildcards * and ** to make it more versatile!

• To display a message on all pages, use /** as the URI.

• If you want to target one specific page, use its URI, i.e /about-us/the-team

• You can also target all subpages of a directory with *: /about-us/* will match /about-us/the-team and /about-us/the-company

• The ** wildcard will also match any subdirectory: /about-us/** will match /about-us/team/europe

Optional Attributes

Several configurations are available as standard HTML data attributes to maximize compatibility across browsers.

<script
  src="{WIDGET_URL}"
  id="clevy-widget"
  data-position="left"
  data-metadata="%7B%22firstname%22%3A%22Jane%22%2C%22email%22%3A%22jane.doe%40company.com%22%7D"
  async>
</script>

data-position

By default, the widget will be displayed on the right side of the screen. To display the widget on the left instead, simply add data-position="left".

data-metadata

To add custom metadata in a widget (see this page for more information about injecting metadata in the assistant), you need to add a data-metadata attribute to the widget initialization script tag that contains the encoded (with javascript's encodeURIComponent function) JSON string of the metadata you want to inject.

For example: data-metadata="%7B%22email%22%3A%22jane.doe%40company.com%22%7D"

data-logo-url

You can configure a custom image to be used as the widget logo by setting this parameter to the URL of your image. You can use a transparent png or a svg to achieve this effect below, or directly use a square image (it will be rounded automatically) without a transparent background to use as the logo.

For example: data-logo-url="https://cdn.clevy.io/clevy-logo-square-white.png"

data-launcher-fill, data-launcher-background

These two parameters let you change the fill color of the default icons, as well as the background for the launcher button.

Any valid CSS value for these elements is accepted. The default values are:

<script src="{WIDGET_URL}"
  id="clevy-widget"
  data-launcher-fill="#ffffff"
  data-launcher-background="linear-gradient(135deg, #4f89fc 0, #1965ff 51%, #104dc7 100%)"
  async></script>

data-force-open

Force the widget to open as soon as the script is loaded. Not recommended as it might be a bit agressive for the visitors of the page, but may be useful in some cases!

<script src="{WIDGET_URL}"
  id="clevy-widget"
  data-force-open="true"
  async></script>

data-ref

Set the Assistant's ref param to trigger a specific flow or step.

<script src="{WIDGET_URL}"
  id="clevy-widget"
  data-ref="someRefParam"
  async></script>

Every time you login to visit your chatbot, you will be greeted by your chatbot's Dashboard. It gives you a birds-eye view over how you are doing with your chatbot so far, and provides you with some hints on how you can improve your chatbot.

Here is what it looks like:

You will find 2 different panels: the Assistant and the Checklist. Let's see what each panel does!

Assistant panel

The Assistant, taking the form of a simple chatbot, will help you quickly identify the current status of your chatbot and give you hints into what you could improve to make an even better chatbot. There are 2 sections, corresponding to the 2 major phases of preparing a chatbot for production: development, and deployment.

The Development assistant will lead you to add more flows to your bot, remember more information about your end users and add more capabilities with the help of integrations and custom apps.

The Deployment assistant will help you add your chatbot to a communication channel or manage your existing channels.

Checklist panel

The checklist will help you quickly identify areas where you can improve your chatbot. It tells you what is missing to make your chatbot as complete as possible in the form of a simple to-do list of what most good chatbots should be doing.

Make sure every item of the checklist is ticked, and you will be on your path to a great chatbot!

Activity panel

Another section that's very important is the Activity page.

This page, as the name indicates, gives you a high-level overview over your chatbot's activity in the past 3 months. If you are seeing a steady increase in usage, then you are probably doing things right. However, if your numbers are stalling or decreasing, perhaps you can take some action like sending a broadcast or adding new content?

We trust that you will find The Dashboard quite instructive in your path to create the greatest possible chatbot!

CSML Studio also comes with a number of tools helping you perform day-to-day tasks such as generating QR codes, manipulating dates and times, or scheduling conversation events in the future.

Scheduler

The scheduler is a good way to plan events to happen at a later time. There are 2 types of scheduled events:

• webhook, when you want a certain URL to be notified at a later time

• broadcast, when you want to create a new conversation with the user later

To install the CSML scheduler, go to Apps > Available Integrations > Scheduler, and click Install.

Example scenario

Imagine an e-commerce chatbot where the user leaves the conversation before checkout, but has items in their cart. In that situation, you might want to send them a reminder a few hours later that they have items in their shopping cart and they might not want to loose them. Heck, why not throw a discount code with it?

Of course, if the user did go through with their order, you want to cancel this reminder, because it does not make sense to keep it.

Here is what this scenario would look like in CSML:

start:
  say "Thanks for shopping with us!"
  goto shop

shop:
  // cancel any existing reminder
  if (sched) do App("utils/scheduler", action="cancel", schedule_id="cart_reminder")
  // ... get the user to buy some items
  say Question("Select an item to buy", buttons=[Button("Mascara"), Button("Perfume")])
  hold
  // then add a new reminder with ID "cart_reminder"
  remember sched = App("utils/scheduler", delay="1 hr", flow_id="remind_cart", schedule_id="cart_reminder")
  
  say "You have {{cart.count}} items in your shopping cart, for a total of ${{cart.total}}"
  say Question(
    "What do you want to do?",
    button_type="quick_reply",
    buttons=[
      Button("Continue shopping 🛍") as shop,
      Button("Go to checkout 💵") as checkout,
    ]
  )
  hold
  // the user wants to continue shopping, let them do that
  if (event.match(shop)) {
    goto shop
  }
  goto checkout

checkout:
  // execute the order from the user
  say "Go to stripe payment page to pay here: XXX"
  hold
  // no need to remind the user anymore, they already paid
  if (sched) do App("utils/scheduler", action="cancel", schedule_id="cart_reminder")

Read below for more information on how to create scheduled items.

Scheduling a webhook call

You can schedule a POST request to a webhook using something like the following:

do sched = App(
    "utils/scheduler",
    action = "webhook",
    url = "https://my.url.com/whatever",
    body = { "some": ["custom", "data"] },
    delay = "10 min",
)
say "Created scheduled event with ID {{sched.result.schedule_id}}"

This means that in about 10 minutes, the endpoint https://my.url.com/whatever will receive a POST request containing the body { "some": ["custom", "data"] }.

Scheduling a broadcast

You can schedule a broadcast to the current user with something like the following:

do sched = App(
    "utils/scheduler",
    action = "broadcast",
    flow_id = "nameOfFlow",
    metadata = { "some": ["custom", "data"] },
    delay = "3 hrs",
)
say "Created scheduled event with ID {{sched.result.schedule_id}}"

This means that in about 30 minutes, the user will receive a new conversation initiated by the chatbot from flow nameOfFlow with the given additional metadata.

Cancelling a schedule

It is possible to cancel a scheduled event by calling the following app, where schedule_id is the ID of the schedule you want to cancel:

do App(
    "utils/scheduler",
    action = "cancel",
    schedule_id = schedule_id
)

Example response

{
    "success": true,
    "result": {
        "action": "broadcast",
        "flow_id": "remind_cart",
        "schedule_id": "some-id",
        "scheduled_at": "2020-07-09T20:02:57.255Z",
        "scheduled_at_unix": 1594324977
    }
}

Caveats

• Events will be executed within 1 minute after your event is scheduled.

• If you do not set your own schedule_id, a random schedule_id will be generated.

• You can use the delay (with either human-readable times, such as "1 hr", "5 min" or a number of milliseconds) or the schedule_time (an ISO-formatted time string OR unix timestamp integer describing when to schedule the event. Example: 1592843603, "2020-06-22T16:33:44.377Z") parameters to set the time for your event.

• You can schedule events at any point within the next 1 minute - 1 month.

• Failed events will not be retried. We guarantee that the event will go off, but make sure that your endpoint is available at the time of the scheduled webhook, or that the channel supports scheduled broadcasts.

CSML (Conversational Standard Meta Language) is an open-source programming language dedicated to building chatbots.

It acts as a linguistic/syntactic abstraction layer, designed for humans who want to let other humans interact with any machine, in any setting. The syntax is designed to be learned in a matter of minutes, but also scales to any complexity of chatbot.

CSML handles seamlessy and automatically short and long-term memory slots, metadata injection, and can be plugged in with any external system by means of channel integrations or custom APIs, as well as consume scripts in any programming languages using built-in parallelized runtimes.

To learn more about CSML, you can read this article.

Build your chatbot with CSML Studio

The easiest way to develop CSML chatbots is by using the CSML development studio, using a sample bot available in your library or by creating your own.

Each bot gives you a full access to the CSML framework - a set of specialized tools to make and customize your chatbots : code editor, chatbox, apps, functions and files library, analytics and channels.

Create your own conversational experiences

You can create your own conversations by modifying an existing flow or creating your own.

A flow is a CSML file which contains several steps to be followed during a conversation with a user. The first instructions have to be placed in the start step, then you can move from a step to the next one using goto stepname, and finish the current conversation using goto end. Each step contains instructions on how to handle the interactions within the step: what to say, what to remember, where to go...

For the bot to say a sentence, you just need to use the keyword say followed by the type of message you want to send.The keyword say allows:

• to display a message: text, questions, urls, components (image, video, audio, buttons…)

• to simulate behaviors, such as waiting time (Wait) or message composition (Typing)

Manage interactions

Like a human, a chatbot is supposed to understand and react to messages sent by the user.

In a conversational logic, CSML allows the chatbot to wait for a user answer using the keyword hold, and interpret the expected user input (called event) to trigger an action.

Here is an example of a simple interaction where the bot is asking if the user likes guitar and waiting for two specific answers in order to trigger actions.

Memory and local variables

Memory is essential in the CSML logic. When two people are chatting, they constantly memorize and update information to be reused in future discussions. CSML provides two types of variables: local variables, with a very short life cycle, and persistent variables, called memories.

The memories are assigned as followed use the keyword remember and can be reused in every step or in a future conversation, while the local variables are executed within one step, assigned with the use keyword.

You can output any variable into a string value with the double curly braces.

Connect apps and execute your own functions

You can select an existing integration in the apps library or add your own function coded in any language. Find a few examples in our GitHub repository and how to use functions in our documentation.

Once your function is uploaded, you can test it and call it in a CSML flow. Read more about functions and apps here!

Deploy your chatbot

Once your chatbot is ready to chat with your users, you can select the channel you want to connect on. For example, using the CSML Studio you can connect your bots to Slack, Messenger, Whatsapp and other channels, or use the CSML Client API to receive requests.

Ready to experience CSML?

CSML Apps are a great way to extend the capabilities of your CSML chatbot by integrating other products with your bot without writing any additional code. CSML Studio provides a number of ready-to-user integrations (over 50 and growing!), that make it possible to integrate your chatbot with the most popular services and applications on the market.

CSML Studio integrations are ready to use. To configure an integration, you only need to configure the required credentials for this app (but some don't require any authentication!). The app's description will have the information on how to get setup.

Example: Giphy app

For instance, if you are looking to add some fun Gifs to your bot, you can try our Giphy integration. To get started, go to Apps > Available Integrations > Giphy.

Simply click on Install, and you are done! Some apps require credentials or API keys, but this one does not. If that's the case you are prompted to add environment variables upon installation.

Then, to use the app in your code, you can use it like this:

start:
  do gifs = App("giphy", action="gif", query="hello")
  say Image(gifs[0])
  goto end

In order to connect your users to various services, you may need to authenticate users. There are several ways to do this, depending on the authentication methods that are available in the 3rd-party service.

Using Chatbot-wide Service Accounts

CSML chatbots run in a secure server, which means that you can load credentials for the service you want to access in your chatbot's environment variables or either dynamically or statically accessing variables inside a flow. If a single set of credentials lets all your users access the service, it means that you probably created a dedicated service account, an account specifically made for the chatbot to access your service with credentials that all users will use to perform the action they want to do.

This method is usually simple to implement (generate once and for all a set of credentials and load it in the chatbot) but has a major drawback: the same credentials are used for all of your users, which are now only differentiated between them by other means (for example, if the ID key is their email address, you could send them an email with a code to that email address to make sure that they are who they claim they are).

A good example of a service account is for things like database credentials, such as MySQL, MongoDB, or event cloud-based databases such as Airtable or Google Sheets. You will likely use the same database for all of your users: hence, one set of credentials should be stored on the server (never expose them to the end users!) and used for all requests to that service.

Using an OAuth2 Flow

In some cases, you may need to authenticate each user separately with their own separate authentication token, or the service does not support creating service accounts. For those cases and on supported channels (Web chat), we provide you with a generic OAuth 2 authorization component. To learn more about OAuth, this website has a lot of very useful information:

To initialize an OAuth flow for a given user, you should start by generating an OAuth App on the service you are going to use, in order to retrieve a client_id and client_secret values. You should also find the service's authorization endpoint (authorization_endpoint) as well as the endpoint where you will generate the access token (token_endpoint).

As an example, Github lets you create custom OAuth apps by visiting https://github.com/settings/developers. As an aside, the "Personal Access Token" method that they offer is similar to creating a service account, but will perform all the API calls as they were made specifically by yourself, and never on behalf of the enduser. It may or may not let you build what you are looking for, hence the OAuth method, which lets the user perform all the calls as themselves.

You should then generate a Client Secret. NEVER share this value publicly!

We also need the Authorization Endpoint and Token Endpoint values, which we usually find in the API documentation in the "Auth" section. Sure enough, for github, this information can be found here:

• Authorization endpoint: https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#1-request-a-users-github-identity

• Token endpoint: https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github

You will also need to pass a specific scope in the OAuth request, so that the generated access token has the right permissions for the calls you want to perform. How the scopes work is usually explained in the service's documentation.

Finally, in your CSML Studio code, add the following few lines (adapt with your own OAuth values):

say OAuthRequest(
    client_id="XXXXX",
    client_secret="YYYYYY",
    authorization_endpoint="https://github.com/login/oauth/authorize",
    token_endpoint="https://github.com/login/oauth/access_token",
    scope="repo user",
    button=Button("Login with Github", payload="OAUTH_SUCCESS") as success
)
hold

This will display the following button:

If the response matches the button, it means that the OAuth flow succeeded. Otherwise, it was not successful (or the user did not authenticate at all).

if (event.match(success)) {
  say "Your access token is: {{event.access_token}}"
}
else {
  say "No access token found in response. Error cause: {{event}}"
}

Using the access token, you can then start authenticating your API calls to the given service!

do listRepos = HTTP("https://api.github.com/user/repos").set({
  "Authorization": "token {{token}}",
  "Accept": "application/vnd.github+json"
}).send()

Chatbots are great, but sometimes your users will need some extra human help to go beyond what the chatbot can do. With CSML Studio, you can decide to bypass CSML and get your users to talk to a human agent instead! This is especially useful if the user needs help beyond what the chatbot can propose.

In order to get your users to talk to your human agents over livechat, you will need:

• a CSML chatbot and channel setup

• a supported Livechat platform

• a special flow to handle livechat requests

Using Livechat in your bot

Using livechat in your flows is very easy. You can find an example implementation to import in CSML Studio here on github.

To start a livechat session, the user needs to specifically request a livechat session with an available agent. This is achieved by getting the user to send the payload LIVECHAT_SESSION_START. When this happens, your CSML chatbot stops receiving events, and all messages are sent to the livechat backend of your choice.

To end a session, the user must send the payload LIVECHAT_SESSION_END . To do this, we recommend that your agent sends a "signing off" message containing that payload, which will be automatically transformed into an adequate button.

The session will also expire if no message is exchanged between the agent and the user within 60 minutes by default (or the timeout configured in the livechat settings panel). When that happens, an event is sent to your bot with the payload LIVECHAT_SESSION_EXPIRED.

This example flow explains in detail the lifecycle of a livechat request:

Configuring Livechat

We have several livechat solution providers, we encourage to try them all to see what fits your use case best! There is usually a free version available to try their product.

Once you have configured the livechat integration, you can also set other parameters:

• Livechat session timeout: this is the maximum amount of time a livechat session will remain active if no message is exchanged between the agent and the user. Any message sent from either side will reset that window. Default: 1hr.

• Session end message and button label: to end a session, the agent should send the user a "LIVECHAT_SESSION_END" event, which will be transposed to a text and button for the user to click on, to confirm they do want to end the livechat session. If the user does not click the button or says anything else, the session continues. This field helps you configure that message.

Chatwoot is an open-source livechat platform, with an online SaaS version as well as a self-hosted version. If you are looking for a livechat solution that you can have full control over, or with a free plan if you want the SaaS version, we recommend Chatwoot!

To get started, go to your bot's Settings > Livechat then select Chatwoot as your livechat support platform.

You will need to retrieve:

• the URL of your Chatwoot instance. If you are using chatwoot.com, it will be https://app.chatwoot.com

• your access token (which you can find at the bottom of your profile settings) and

Hit Save, and a dedicated inbox will be created for you!

Canned Responses

We recommend you configure a "Signing off" canned response in Chatwoot to trigger the LIVECHAT_SESSION_END event under Settings > Canned Responses.

You can simply copy and paste the text below, or adjust to your liking - just make sure that the LIVECHAT_SESSION_END is at the end of the content.

Let us know if we can do anything else for you - we are here to help.

LIVECHAT_SESSION_END

To create a CSML Studio Assistant, click on the channels menu then on create new channel.

Click on Assistant, add a name and a description (you can change it later), then click on Submit.

Your Assistant is now created and ready to use! There are two ways to use your Assistant: either by visiting the link at the top, or by adding the widget link for integrating it into your existing website. It works on mobile too!

In the AI Rules section of CSML Studio, you will find a way to configure flow commands for any of your flows. This section makes it easy to see in one single screen all the rules that govern the triggering of any of your flows!

Commands are words or sentences (or intents, when NLU is configured) that will trigger a given flow. For example, in the example below, if a user says "Hi", no matter where they are in the bot, they will be redirected to the Welcome flow:

You can have as many AI Rules as you want on as many flows as you want. The commands are case-insensitive, so for example "Hi", "hi", "HI" and "hI" will all trigger the Welcome flow. Also, if the same rule is used as an input to two different flows, the triggered flow will be randomly chosen among the target flows.

This feature can also be used in conjunction with any Preprocessing or NLP configured in your bot. For instance, if after going through a NLP service, an intent is detected, the intent name can be used as a command for any given flow (with the intent: prefix, i.e intent:myIntentName). For instance, this is how an intent called DemoContext would be handled with AI Rules:

Referral Parameter

You can launch a specific flow (and step) instead of the default Welcome Flow when loading the Assistant by providing a ref query parameter in its URL.

To force the launch of a specific flow when opening the Assistant URL, use the following special syntax:

# will redirect to the step NAME_OF_STEP in the flow called NAME_OF_FLOW
https://chat.csml.dev/s/abc12345678901234?ref=target:NAME_OF_STEP@NAME_OF_FLOW

# or, if no step is provided, the `start` step will be used
https://chat.csml.dev/s/abc12345678901234?ref=target:NAME_OF_FLOW

Injecting Conversation Metadata

By default, the Assistant channel does not include any specific context about the conversation (see the _metadata object documentation). In some cases, it can be useful to load the Assistant (or Widget) with pre-existing metadata.

Some common scenarios:

• the bot is loaded in a website where the user is already known: in that case, we may be interested in injecting the user's context (name, email...) inside the conversation.

• the user is authentified on the parent website: in that case, we may want to inject an authentication token into the user's conversation for subsequent calls.

• the same bot is used across several websites and we want to know which website the user is currently visiting: in that case we can inject a unique website identifier into the conversation.

The injected data is available in the _metadata global variable, available in every flow. The code of the example above is:

start:
  say "Hi {{_metadata.firstname}}"
  say QuickReply(
    "Your email address is: {{_metadata.email}}. Do you confirm?",
    buttons=[Button("yes"), Button("no")]
  )
  hold

To add custom metadata in your Assistant, simply add the encoded (with javascript's encodeURIComponent function) JSON string of the metadata you want to inject to the query parameters of the URL. The URL of the Assistant in the example above would be:

{ASSISTANT_URL}?metadata=%7B%22firstname%22%3A%22Jane%22%2C%22email%22%3A%22jane.doe%40company.com%22%7D

Customizing the UI

You can change the appearance of the Assistant by visiting the Design tab of the configuration panel. This lets you have even more control over the final experience for your end users, and match your own branding even better!

Many elements are configurable:

• Chatbot avatar, header card color and background image

• User bubble colors

• Hiding the CSML branding

• Disabling the speech input

• And many others!

General information

The settings panel has a few options to allow you to configure the Assistant. Each Assistant must have a name, and you can also add an optional description and logo.

Welcome flow

When a user arrives on the page, the chatbot welcomes them with a flow. It can be any flow, but by default it is the Default flow.

If you do not want a welcome interaction at all, create an empty flow and use that as the Welcome flow!

Menu

The Assistant channels lets you add shortcuts to either flows or external websites:

This will show as a list of searchable shortcuts in the sidebar in full-screen view, or at the top of the input bar in mobile/widget view:

Autocomplete

The autocomplete feature helps your chatbot provide a list of up to 5 items that are contextualized to what the user is currently typing. Think of it as quickly hitting one of the first google search results!

To configure Autocomplete, you need to have a backend endpoint that will handle the requests and respond accordingly. You can configure this endpoint in the Assistant's configuration panel:

The request that will be performed by the Assistant will be as follows:

Your endpoint must return results within 5 seconds as an application/json content-type, formatted as an array of maximum 5 results containing a title, optional highlighting matches, and the corresponding payload.

When a user selects a result, it will behave as a button click where the text is displayed and the payload is sent to the chatbot.

Enabling/disabling autocomplete

If an autocomplete endpoint is set, it will be enabled by default. However, it can be disabled or reenabled dynamically in your CSML script:

Using the CSML Studio, you can connect and deploy your chatbot on a number of communication channels. Each channel has its own set of limitations and features, so when developing a chatbot you must always keep in mind how your end users will be using your chatbot. Vocal chatbots are not consumed the same way as textual chatbot, so it sometimes makes sense to design an entirely separate user experience for channel.

Default component behavior

CSML can not compensate for limitations in each third-party channel. Instead, it provides a universal way to describe conversational components and an adaptor will try to match with what is available on that channel.

In most cases, CSML will try to find a sensible default behavior for each component on each channel. For instance, some channels can not display actual buttons so they will be displayed as plain text: in that case, a good practice is to place buttons in an ordered list and accept the buttons number as a trigger for that button.

Native channel behavior

Most channels will provide a similar way of accessing native behavior for situations where CSML Components are not sufficient.

Differentiating between channels

If you plan to use the same chatbot on multiple channels at the same time, there may be times where you need your chatbot to have a different behavior based on the type of channel: changing a text, displaying a static image instead of a video, altering the buttons...

A broadcast is a message sent proactively from the bot to a user, without the user sending a request first. It is a great way to reengage your users, for example to remind them about a conversation they didn't finish, or let them know a product they ordered has been shipped.

POST /broadcasts

Send a broadcast on the requested channel (supported channels only) to the requested client. Broadcast requests are queued and usually sent within a few seconds. If a target is unavailable, no error is generated.

Request example

Response example

To uninstall a channel, you need to delete the channel both on Workplace, and on CSML Studio. Only removing the channel on CSML Studio will leave the chatbot visible to Workplace users.

To remove the bot from Workplace, visit the and find your bot in the list of available bots.

Click on Uninstall then confirm. Your bot will immediately be removed from Workplace chat, however users that already talked to the bot will still be able to find their conversation history.

After this is done, you can safely remove the channel from CSML Studio as well.

The installation process of a Microsoft Teams chatbot has many steps. You will also need to be able to create an app and bot on your Microsoft Teams and Azure tenants. Once

To get started, visit Channels > Connect new channel > Microsoft Teams (beta).

1. Create a bot on Microsoft Bot Framework

Retrieve your Messaging endpoint from the Studio configuration page:

Next, select Create Microsoft App ID and password.

You will be taken to a new page on Azure to register a new app (or list existing apps). Click on New registration.

On the next page, fill in a Name, select the Accounts in any organizational directory - Multitenant option (the reason is that you will be using the Microsoft Bot Framework tenant for your bot, which will require access to the app as well).

You can leave the Redirect URI fields empty, then click Register.

On the next page, create a New client secret, give it a name and a validity date (if you select anything other than Never, you will need to come back occasionally and get a new secret), submit, then take note of the given secret (you will never be able to see it again).

Now, go to Overview and take note of the App ID for later. After that, you can close this window.

Back to the Bot Framework configuration window, paste the Microsoft App ID you just created where required, then scroll to the bottom of the page, check the "I Agree" box and click Register.

2. Registering Microsoft Teams as a channel on Bot Framework

After registering your bot, you need to add Microsoft Teams as a channel. To do so, simply click on the Configure Microsoft Teams channel icon.

On the next page, simply click Save without doing anything else, check the "I Agree" box, and submit.

You can now close this window as well and go back to the CSML Studio.

3. Connect the bot to CSML Studio

Back to the CSML Studio channel creation page, fill in the App ID, App secret and Bot handle, then submit.

In the next page, you can generate and download a Manifest for your Microsoft Teams chatbot. A manifest is a configuration file that you will be able to upload on Microsoft Teams in order to deploy your chatbot to your team. It contains all the information required for Microsoft to correctly install and display your bot to every user.

Upon saving, a manifest.zip file will be downloaded to your computer. Save it somewhere for the next (and final) installation step.

4. Deploy your bot on Microsoft Teams

On Microsoft Teams (web or desktop), find the Apps panel, then select Upload custom app > Upload for MY_TEAM (obviously, replace MY_TEAM with the name of your own team).

Then, click on the App you just uploaded, then select Add.

Voilà! Your bot is now available to all users in your team:

You can find similar configuration settings between and Workchat channels. However, Workchat being a professional, internal-only communication channel, there are some additional options you can play with.

Broadcast

The Broadcast feature allows you to trigger any flow for any given user or list of users. To use the broadcast feature, click on Send broadcast to open a configuration popup.

• Under Flow, select the flow you want to trigger

• Under Targets, list the emails (one per line) you want to receive the broadcast

• Under Context, you can optionally add any additional context that you want to set in the _metadata object for this broadcast

Once you hit Send, the broadcast will be sent immediately.

Workplace Chat is very, very similar to Messenger (except that it's grey). Please refer to Messenger's CSML documentation:

Broadcasts

Broadcasts can be sent without any limitation to any of your Workplace Chat users, with either their valid Workplace email address or ID as the user_id.

Event Metadata

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

Installing a Workchat bot on CSML Studio is very easy, as it only takes one click. However, it does require admin rights on your Workplace instance.

Go to Channels > Connect a new Channel > Workplace Chat.

If you are a Workplace admin, simply click on the button and follow the instructions. Otherwise, copy the URL just below and send it to a Workplace admin. They will be able to complete the installation flow autonomously, even if they do not have a CSML Studio account. After clicking on the button or link, you will be redirected to the app setup page on Workplace.

From there, you can configure its name, description and logo by clicking on Customize.

You can also set which groups will have access to the bot.

• If you want everyone to have access to this chatbot, leave the All groups box checked.

• If you want to restrict access to the members of specific groups, check Specific groups instead, then select which groups are allowed to access the bot. Users that are not in one of the selected groups will not be able to search for or chat with the bot in Workchat.

Click on Add to Workplace and you are done!

Text

The Text component also supports some basic Markdown:

Typing, Wait

Display a typing indicator for the requested time expressed in milliseconds. Obviously, Wait is also supported (it simply does not display a typing indicator or anything for the given duration).

Image

Question, Button

If you need to retrieve a specific data when clicking on either button, use the payload argument of the Button component:

QuickReply

Video, Audio

The Video component supports links to mp4 files, as well as Youtube, Vimeo and Dailymotion URLs. The Audio component supports links to mp3 files, as well as Spotify, Soundcloud and Deezer URLs.

Url

The Url component will automatically retrieve the target's favicon if available. If a text parameter is present, it will be used as the component's title.

Carousel, Card

A Carousel is essentially a collection of Card elements A single Card will display as a Carousel of 1 element. Each Card can have a maximum of 2 Button elements.

The cards themselves can be made clickable by adding an optional default_action Url() parameter:

The carousel can also automatically navigate horizontaly by adding the optional autoplay parameter (which defaults to false):

Calendar

This component will display a rich calendar in the webapp. By default, when passed with no argument, a simple single-date datepicker will appear:

Optional parameters allow to set a min_date and/or max_date (by unix timestamp, in milliseconds) or an input_mode to accept single (the default) multiple or range inputs by the user:

The event value of a Calendar input will be comma-separated values of all user inputs. Also, event.input_mode will be set to the mode of the requested calendar, so that you can differenciate between single, multiple and range modes when receiving values.

Input

To gain some control over what a user can enter in a form (for example, if you need to make sure they only enter an email address or a valid number when required), you can also use the Input component.

There are several variants of input fields: email, text, textarea, number and password. By default, inputs are type="text". All parameters are optional, and the basic usage is as follows:

A completely bare say Input() component will result in a simple, empty text input.

Inputs with type="number" can have some different parameters, just like HTML inputs (all are optional as well):

Radio

Display a radio buttons component:

Multiselect, Checkbox

If you want to let users select multiple options, the Multiselect() or `Checkbox()` components are a great solution. Users will be able to select any number of options in the given list. You can force a min and max number of choices, or if required=true, it means that at least one option must be selected to continue.

Both the Multiselect and Checkbox components work exactly the same, only the display will be different. Try both to find out which one suits you best!

When several options are selected, you will receive a comma-separated list of the corresponding payloads (not necessarily the button's title!), in the order they were selected by the user.

Dropdown

Like the Radio component, the Dropdown lets users pick an option from a list:

LaTeX

You can also add LaTeX inline in any standard text like by encapsulating it inside {latex}...{/latex} tags:

Signature

You can display a simple signature field i.e to collect user consent and receive it as a png file.

The Workplace Chat channel offers more or less the same features and limitations as the channel, as they are built on top of the same platform. However, there are some key differences, in how they are installed, configured and what specific features and limitations they offer.

Broadcast API

The Microsoft Teams channel supports the .

• The client user_id must be set to a valid conversationId (as returned in every conversation's metadata).

• No broadcast can be sent to a user that has not already actively interacted with the chatbot.

Event Metadata

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

Creating a Telegram chatbot is particularly easy. You only need to get a regular Telegram account, then to interact with on Telegram, which is a built-in bot that will help you setup your own bot!

Telegram's @BotFather

BotFather lets you customize your bot even more. You can use the following commands:

• /setname to change the bot's name

• /setuserpic to change the bot's profile picture

• /setdescription and /setabouttext to change the bot's description/about texts

This is also a perfect way to try the Telegram commands feature, which is very powerful!

CSML Studio Setup

Once you have received the bot's token, go to your bot's Channels page and click on Telegram to create a new Telegram chatbot.

Once this is done, you will be able to setup a few commands for your own bot. The /start command is mandatory and can not be removed (but you can change its description), and it will always trigger the chatbot's welcome flow. You can add more commands to your bot, which will show if you start typing / or click on the corresponding symbol in the Telegram interface:

Text

Google Chat lets you format text. So you can either use regular text or formatted text:

Typing, Wait

Google Chat does not have a typing indicator. Typings are simply interpreted as delays.

Url, Audio, File

Google Chat unfurls URLs and displays a preview of the content of the page. For instance:

Google does not provide a way to display an audio player or to upload a file from the bot. These components will be rendered as simple Urls.

Image

Video

In some cases, Google Chat will be able to automatically display a video player in the conversation. This is obviously the case with Youtube videos, but it also works with some other players.

In other cases, you can add some optional parameters to the video to wrap it and render it better:

• title - the title that will appear on the video card

• thumbnail_url - the url to the thumbnail image

• button - the clickable button to open the video

Carousel, Card

There is no concept of Carousel in Google Chat, but cards can be stacked vertically. When using a Carousel component, this is the end result:

Raw objects

This example renders a raw image:

Slash Commands

In the Google Chat configuration panel, you can setup slash commands for your bot. These are nice ways to force trigger a CSML flow.

To setup a slash command, you need to create the command like so:

Then, in the AI Rules panel in CSML Studio, add a rule for this command triggering a specific flow:

When the command is used, the specified flow will be triggered with the following payload:

Event Metadata

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

Setup Twilio

Step 1: Purchase a Twilio phone number compatible with Programmable Messaging

To get started, you will need to create a Twilio account and purchase a phone number in the country of your choice. . The only point of attention is that you must make sure that the number you purchase has Messaging capabilities. Please keep in mind that depending on your country of origin, the requirements may differ, and Twilio may ask you for business verification. Keep track of this phone number (including the country code) as you are going to need to add it later to CSML Studio!

Step 2: Configure the messaging webhook

To configure the webhook, you can either use a TwiML app, or directly set a webhook in the messaging configuration panel. Either way, you will need to set the HTTP POST webhook to , for example like so:

Step 3: Security and Authorization

Setup CSML Studio

To setup your Twilio SMS channel in CSML Studio, you will simply need to visit the Channels section and create a new Twilio SMS channel. Then simply fill the required fields with the information you gathered earlier.

Once you click on Submit, your bot is ready to use!

Components

As you can expect, not all CSML components work well with a SMS chatbot, as there is no support for any visual component or buttons. However you can use all of the following standard components:

• Text

• Question (buttons will be added in a new line under the question's title)

• Image

Other components will be automatically reduced to simple text components.

Metadata

Each call made to CSML Studio will have a number of metadata, based on what information is provided by Twilio. An example _metadata object would look like this:

Prerequisites

There are two prerequisites for installing a Whatsapp bot in the CSML Studio.

1. you MUST have a verified Meta Business account

2. you MUST have a Meta Developer account

And more generally, you must be able to follow this guide to setup a Meta app correctly: .

Connecting Whatsapp to CSML Studio

In your bot in CSML Studio, go to Channels > Connect a new channel, then select Whatsapp.

In the next screen, enter a name and description for your channel (it is purely informational and can be changed later) and add the required credentials.

The App ID and App Secret can be found in the app's Basic Settings page:

The User Access Token, Phone Number ID (and not the actual phone number!) and WhatsApp Business Account ID can be foud under Whatsapp > Getting Started. You can start with one of the Test numbers provided by Facebook, but in production you will want to change that to your own phone number once it is properly configured.

Then, click Save to setup the channel. In the following page, you will also receive your Webhook configuration parameters:

Use these parameters in the Whatsapp > Configuration page under Callback URL and Verify token. Make sure to also subscribe to the messages Webhook field.

Setup a Google Chat service account

are the primary way to interact with Google Cloud resources, and setting up a chatbot is no different.

The first step is to create a new Google Cloud project. Visit and fill the required fields:

In the next screen, grant the Project > Editor role to the service account:

The third step (Grant users access to this service account) is optional and can be skipped. Click on Done to create the service account.

Once the service account is created, you will need to generate a key. Select the service account, click on Add Key > Create New Key, select JSON as the Key type, and save the file.

Setup the channel in CSML Studio

In CSML Studio, under Channels > Connect a new channel, select the Google Chat channel. In the next screen, give your channel a name, a description and upload your service account credentials.

In the next screen, you can configure the bot's Welcome Flow, and copy the Chatbot Endpoint URL, which we will use in the next step.

Connect the chatbot with Google Chat

You can select Bot works in direct messages or Bot works in rooms... depending on the experience you want to give to users.

Under Bot URL, paste the Chatbot Endpoint URL from the previous step.

Click Save, and you are all set!

Finding the bot in Google Chat

To find your bot in Google Chat, users have to navigate to the Bot catalog, which can be reached either by clicking the + icon next to the bot section of the left sidebar, or by searching for the name of the bot directly:

Upon activating the bot for the first time, the Welcome Message will be displayed:

Setup Twilio

Step 1: Purchase a Twilio phone number compatible with Programmable Voice

To get started, you will need to create a Twilio account and purchase a phone number in the country of your choice. . The only point of attention is that you must make sure that the number you purchase has Voice capabilities. Please keep in mind that depending on your country of origin, the requirements may differ, and Twilio may ask you for business verification. Keep track of this phone number (including the country code) as you are going to need to add it later to CSML Studio!

Step 2: Configure a TwiML App

TwiML is Twilio's own markup language for connecting with their programmable interfaces. You will need to create a new app by and clicking on Create a new app, then fill the Voice Request URL and provide with this URL: .

Once you have created this app, find its Application SID by clicking on its name again on the list of TwiML apps, and keep this information for later.

Step 3: Security and Authorization

Setup CSML Studio

To setup your Twilio Callbot in CSML Studio, you will simply need to visit the Channels section and create a new Twilio (Voice) channel. Then simply fill the required fields with the information you gathered earlier.

Once you click on Submit, your bot is ready to use!

Components

Most components are available on Telegram, however Carousel components are currently not supported. Typing components are also displayed as simple Wait components.

Broadcast

You can send a broadcast to a given user by using _metadata.id as their user_id with the broadcast API or the broadcast interface in the corresponding tab in the channel's settings. It requires that the user has already interacted with the chatbot before (you can not simply send a message to a user's @username).

You can add custom metadata as well!

Event Metadata

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

The Slack integration provides you with a Manifest that allows you to setup most of the heavy Slack App configuration in seconds. To get started, simply click on the link provided here:

Simply follow the on-screen instructions until the app is installed to your workspace. You will be required to allow the app to perform the necessary actions - you must be a workspace admin to do that.

You will still need to perform a few actions to correctly setup your app. First, visit the App Manifest menu. It may have an orange warning box at the top: in that case, click the "Click here to verify" link to make that warning disappear. Another way to perform this verification if needed is by visiting Event Subscriptions and performing the same operation.

Next, visit the OAuth & Permissions menu, copy the Bot User Token and save it for later.

Next, select App Home in the left-side menu. Enter a Display Name and a Default Name for your bot and select Always Show My Bot as Online.

At the bottom of the same App Home page, under Show Tabs, make sure the Messages Tab toggle is on and the Allow users to send Slash commands and messages from the messages tab checkbox is checked.

Next, visit Basic Information from the left-side menu, copy the App ID, Client ID, Client Secret and Signing Secret under App Credentials and save them for later.

On the same page, you can also customize the appearance of your chatbot in Slack (image, colors...).

Finally, back in CSML Studio, paste the credentials you retrieved earlier: Bot User Token, App ID, Client ID, Client Secret, Signing Secret, then click on Submit.

You should now be able to see your app in the left sidebar of your Slack workspace, under Apps. This is where you can chat with your slack bot!

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

1. Login with facebook

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

Text

Slack has partial markdown support in text components.

Typing, Wait

In Slack, Wait and Typing have the same behavior. No typing indicator exists in slack, so the bot will simply wait for the duration given (in milliseconds) before the next message is processed.

Question, Button

Slack makes it possible to style your buttons and define a custom payload that is sent to the chatbot on click. Available styles are "danger" and "primary". Slacks recommends to only use primary on one button in a list, and danger even less often.

CSML Studio will also take advantage of Slack's features to update the content of the component when an option is chosen, so that the user's choice appears clearly after they select an option.

Image

Send the URL of an image. Slack will attempt to display it.

Video, Audio, Url

Generic files will render as standard URLs. When it can, Slack will try to display the URL nicely, such as the Wikipedia link below.

Carousel, Card

A Carousel is essentially a collection of Card elements A single Card will display as a Carousel of 1 element.

You can add several Button or Url buttons to your Card components.

Input, Textarea

Radio, Dropdown

Multiselect, Checkbox

Calendar

Full reference

Event Metadata

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

Features

Available components

Whatsapp supports the following components:

• Simple texts

• Wait() and Typing()

• Medias: Image(), Video(), Audio(), File()

• Url()

• Question() and QuickReply()

Markdown is partially supported (only bold, italic and strikethrough).

QR Codes Messages

Whatsapp provides an easy way to generate QR codes that let users reach your chatbot easily. You can read more about it here:

Limitations

Channel Availability

As a security measure, user access tokens expire after about 60 days. If your Whatsapp chatbot remains unused for a longer time, the token will be automatically expired and you will need to reconnect your app to restore it.

Buttons

Whatsapp has a very limited set of interactive components. Buttons for example are textual only, and your users will have to type the actual text of the button

The mapping of Question() and Button() components to text is performed automatically. However you need to set the right title and accepts values in order to correctly match the user's input.

Urls

The Url() component does not support any alternative text or title. Only the given url will be shown as is. For instance, the following code:

Has the following output:

Video

You must upload videos in mp4 format. Videos hosted on platforms such as Youtube, Dailymotion or Vimeo will not display (use the Url() component).