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:

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!

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

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

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.

Build your chatbot with CSML Studio

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

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

• 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

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

Deploy your chatbot

Ready to experience CSML?

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

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

Using SaaS providers

CSML Studio currently supports the following NLP providers:

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

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.

Bot-Wide Environment Variables

When you need to access some static values across all your users and all your flows, you should use Bot Environment Variables.

These values are injected in your conversations under the _env global variable and are accessible everywhere, without ever being injected in the current user's memory. They are also encrypted for enhanced security.

This is a perfect use case for API keys or secrets, as well as global configuration options.

Self-Hosted CSML Engine

If you have strong requirements for data hosting or prefer hosting the CSML Engine on your own servers, you may want to use the On-Premise feature. By using this feature, you have full control over what version of CSML Engine is used at any given time (the Studio will always default to the latest available version otherwise), but you also have the responsibility of maintaining and scaling the engine according to your usage. We recommend that you only use this option if you really know what you are doing or if you have strong legal (i.e data privacy, compliance) requirements for doing so.

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:

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

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.

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

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.

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

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

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

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

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:

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

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

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

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'

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

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.

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

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!

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

curl "https://clients.csml.dev/v1/api/broadcasts" \
     -H 'content-type: application/json' \
     -H 'accept: application/json' \
     -H 'x-api-key: ${X-API-KEY}' \
     -d $'{
  "payload": {
    "content": {
      "flow_id": "myflow"
    },
    "content_type": "flow_trigger"
  },
  "client": {
    "user_id": "some-user-id"
  },
  "metadata": {
    "somekey": "somevalue"
  }
}'

Response example

{
  "request_id": "57d2d4ab-6994-4449-82bf-206619d9d063",
  "client": {
    "user_id": "some-user-id",
    "bot_id": "bc5de819-e4c5-463e-9090-5648fac3a570",
    "channel_id": "b1f74f8d-99b6-40b2-ad64-00ec364bae23"
  },
  "payload": {
    "content_type": "flow_trigger",
    "content": {
      "flow_id": "myflow",
      "close_flows": true
    }
  },
  "metadata": {
    "somekey": "somevalue"
  }
}

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

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.

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

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

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:

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:

Setting up CSML Studio CLI

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

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

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:

curl -X "POST" "https://my.example.com/autocomplete?token=some-auth-token" \
     -H 'Content-Type: application/json;charset=utf-8' \
     -d $'{"text": "Give me the best result"}'

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.

[
  {
    "title": "What is the best result?",
    "matches": {
      "highlights": [
        {
          "word": "What",
          "highlight": false
        },
        {
          "word": "is",
          "highlight": false
        },
        {
          "word": "the",
          "highlight": false
        },
        {
          "word": "best",
          "highlight": true
        },
        {
          "word": "result",
          "highlight": true
        },
        {
          "word": "?",
          "highlight": false
        }
      ],
      "text": "What is the best result?",
      "has_highlights": true
    },
    "payload": "RESULT_ONE_PAYLOAD"
  },
  {
    "title": "Another good result",
    "matches": {
      "highlights": [
        {
          "word": "Another",
          "highlight": false
        },
        {
          "word": "good",
          "highlight": false
        },
        {
          "word": "result",
          "highlight": true
        }
      ],
      "text": "Another nice result",
      "has_highlights": true
    },
    "payload": "ANOTHER_RESULT_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:

say Autocomplete(false)
say Autocomplete(true)

Text

say "His palms are sweaty, knees weak, arms are heavy" // short form
say Text("There's vomit on his sweater already, mom's spaghetti") // long form

The Text component also supports some basic Markdown:

say "He's _nervous_, but **on the surface** he looks [calm and ready](https://www.youtube.com/watch?v=_Yhyp-_hX2s)"

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

say Typing(1000)

Image

say Image("https://images.unsplash.com/photo-1560114928-40f1f1eb26a0")

Question, Button

say Question(
  "Hi! My name is:", // equivalent to title="Hi! My name is:",
  buttons=[Button("What?"), Button("Who?")]
)

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

say Question(
  "Hi! My name is:",
  buttons=[
        Button("What?", payload="btn1"),
        Button("Who?", payload="btn2"),
  ]
)
hold
say "user clicked on button with the {{event}} payload"

QuickReply

say QuickReply(
  "Do you like cheese?",
  buttons=[Button("Yes 🧀"), Button("Also yes 🫕")]
)

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.

say Video("https://www.youtube.com/watch?v=lqBhgEQ4LT0")
say Audio("https://open.spotify.com/track/1xB3YT8Rakvnfcc1dp2kzJ")

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.

say Url("https://www.wikipedia.org/", text="Visit Wikipedia")

// if you don't want to display the URL itself, making it harder
// to identify that it is a link and not just an action button, add `hide_url=true`
say Url("https://www.wikipedia.org/", text="Visit Wikipedia", hide_url=true)

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.

do card1 = Card(
    "The Marshall Mathers LP",
    subtitle="Release date: May 23, 2000",
    image_url="https://upload.wikimedia.org/wikipedia/en/a/ae/The_Marshall_Mathers_LP.jpg",
    buttons=[Button("Listen to this album", payload="marshallmatherslp1")]
)
do card2 = Card(
    "The Slim Shady LP",
    subtitle="Release date: February 23, 1999",
    image_url="https://upload.wikimedia.org/wikipedia/en/3/35/Eminem_-_The_Slim_Shady_LP_CD_cover.jpg",
    buttons=[Button("Listen to this album", payload="theslimshadylp")]
)
do card3 = Card(
    "The Marshall Mathers LP 2",
    subtitle="Release date: November 5, 2013",
    image_url="https://upload.wikimedia.org/wikipedia/en/8/87/The_Marshall_Mathers_LP_2.png",
    buttons=[Button("Listen to this album", payload="marshallmatherslp2")]
)

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

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

do card = Card(
    "The Marshall Mathers LP",
    subtitle="Release date: May 23, 2000",
    default_action=Url("https://en.wikipedia.org/wiki/Eminem"),
    image_url="https://upload.wikimedia.org/wikipedia/en/a/ae/The_Marshall_Mathers_LP.jpg",
    buttons=[Button("Listen to this album", payload="marshallmatherslp1")]
)

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

say Carousel([ card1, card2, card3 ], autoplay=true)

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:

say Calendar()

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:

say Calendar(
    min_date="2021-04-02", // April 2nd, 2021
    max_date="2021-06-18", // June 18th, 2021
    input_mode="range" // can also be "multiple" or "single"
)

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.

// given this sample CSML code
say Calendar(...)
hold
say "{{event.get_content()}}"

// example single mode
{
  "input_mode":"single",
  "payload":"2021-04-07T00:00:00.000+02:00"
}
// example multiple mode
{
  "input_mode":"multiple",
  "payload":"2021-04-07T00:00:00.000+02:00,2021-04-15T00:00:00.000+02:00,2021-04-20T00:00:00.000+02:00"
}
// example range mode
{
  "input_mode":"range",
  "payload":"2021-04-07T00:00:00.000+02:00,2021-04-15T00:00:00.000+02:00"
}

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:

say Input(
  type="text", // default
  title="What is this field?",
  description="Some details about what is expected",
  minlength=0, // for text/email/textarea inputs only
  maxlength=100, // for text/email/textarea inputs only
  required=false,
  placeholder="This is an input",
  default_value="This is set by default",
  submit_label="Submit" // the text for the validation button, defaults to OK
)

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

say Input(
  type="number",
  title="Enter a number",
  min=-14.3,
  max=42,
  // the other parameters from the previous example also apply
)

Radio

Display a radio buttons component:

say Radio(
  // Mandatory
  options = [
    Button("Cats 🐕", payload="meow"),
    Button("Dogs 🐶", payload="woof"),
    Button("Hot dogs 🌭", payload="yummy"),
  ],

  // Optional fields:
  title="What's your favorite animal?",
  description="You can only pick one!",
  selected = "yummy", // Preselect a value
)

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!

// A list of options that are highlighted as you select them
say Multiselect(
  title="Why do you like CSML?",
  description="Select all options that apply!",
  min=2,
  submit_label="Yes, that's it!",
  options=[
    Button("It's easy to learn", payload="easy"),
    Button("It's pretty quick", payload="fast"),
    Button("It's scalable", payload="scalable"),
    Button("It's fun", payload="fun"),
    Button("The mascot 🦜 is cool", payload="pako"),
  ]
)

// The same component also works as a simple checkbox list
say Checkbox(
  title="Why do you like CSML?",
  description="Select all options that apply!",
  min=2,
  submit_label="Yes, that's it!",
  options=[
    Button("It's easy to learn", payload="easy"),
    Button("It's pretty quick", payload="fast"),
    Button("It's scalable", payload="scalable"),
    Button("It's fun", payload="fun"),
    Button("The mascot 🦜 is cool", payload="pako"),
  ]
)

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:

say Dropdown(
  // Mandatory list of options
  options=[
    Button("It's easy to learn", payload="easy"),
    Button("It's pretty quick", payload="fast"),
    Button("It's scalable", payload="scalable"),
    Button("It's fun", payload="fun"),
    Button("The mascot 🦜 is cool", payload="pako"),
  ],

  // Optional parameters
  title="Why do you like CSML?",
  description="Select the principal reason!",
  placeholder="They are all good reasons...",
  selected="easy", // value selected by default
  submit_label="Yes, that's it!",
)

LaTeX

start:
  say LaTeX(
    "\(x^2 + y^2 = z^2\)",
    // If the user has "audio mode" enabled the tts parameter
    // will be used as the basis for the speech synthesis
    tts="This is the Pythagorean theorem!",
  )

  say LaTeX("\\def\\arraystretch{1.5}
   \\begin{array}{c:c:c}
   a & b & c \\\\ \\hline
   d & e & f \\\\
   \\hdashline
   g & h & i
\\end{array}")

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

say "This equation {latex} \(x^2 + y^2 = z^2\) {/latex} is super cool"

Signature

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

// Display a simple signature field
say Signature()

// The field can be customized (all parameters are optional)
say Signature(
  "Please sign here!",
  description="Yes please do!",
  submit_label="I consent"
)

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

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

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"
            }
          }
        ]
      }
    }
  }

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

do channel_type = _metadata._channel.type

// whatsapp can not display clickable buttons
// so we must provide a number to select instead
if (channel_type == "whatsapp-messagebird") say Button("1 - Pick me!")
else if (channel_type == "webapp") say Button("Pick me!")

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",
    }
  ]
}

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.

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!

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

<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

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

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

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!

Broadcast API

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

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.

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:

Injecting Conversation 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:

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!

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

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

Audio

You must upload audio files in mp3 format. Audio files hosted on platforms such as Spotify, Deezer or Soundcloud will not display (use the Url() component).

Files

There is a hard limit of 25MB for all uploaded files (including image, video and audio files).

In a File() component, not all file types are supported. A list of supported file types could not be found, but it is safe to recommend using very common file types only.

The file upload process happens asynchronously on Whatsapp, so messages might show out of order if there is a large upload with not enough time left for its upload before sending the next message.

Carousel, Card

Carousel() and Card() components are not supported.

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:

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.

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!

Setup a Google Chat service account

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:

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

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.

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:

{
  "_channel": {
    "app_id": "10067197168686",
    "name": "test-22032021",
    "type": "workchat"
  },
  "email": "john.doe@company.com",
  "first_name": "John",
  "id": "581595168271418",
  "last_name": "Doe",
  "link": "https://work.facebook.com/app_scoped_user_id/HASH",
  "name": "John Doe",
  "name_format": "{first} {last}",
  "picture": {
    "data": {
      "height": 1016,
      "is_silhouette": false,
      "url": "https://platform-lookaside.fbsbx.com/platform/profilepic/?asid=581595189176358&height=1200&width=1200&ext=NUMBER&hash=HASH",
      "width": 1016
    }
  }
}

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:

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!

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:

Event Metadata

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

{
  "user_id": "U01M7K2U93K",
  "image_192": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=192&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-192.png",
  "avatar_hash": "q126ddaf086f",
  "status_emoji": "",
  "first_name": "John",
  "real_name_normalized": "John",
  "display_name": "",
  "skype": "",
  "phone": "",
  "fields": [],
  "title": "",
  "last_name": "",
  "image_48": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=48&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-48.png",
  "status_text": "",
  "real_name": "John",
  "email": "<mailto:john.doe@company.com|John.Doe@company.com",
  "status_expiration": 0,
  "image_512": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=512&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-512.png",
  "image_24": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=24&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-24.png",
  "image_32": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=32&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-32.png",
  "image_72": "https://secure.gravatar.com/avatar/186ddaf086f2b86827311ojk8a9453dc.jpg?s=72&d=https%3A%2F%2Fa.slack-edge.com%2Fdf10d%2Fimg%2Favatars%2Fava_0002-72.png",
  "display_name_normalized": "",
  "status_text_canonical": "",
  "_channel": {
    "type": "slack",
    "name": "Slack channel",
    "app_id": "A01NUE2CBHC"
  }
}

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.

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!

Conversation design

Designing a callbot is very different from designing a text-based chatbot. There are however some extra rules to make a successful callbot:

• Keep your all your sections short. Nobody wants to listen to (and can remember) a huge block of text!

• This integration supports both speech and DTMF (keypad) inputs. When you can, let the caller use the number keypad on their phone, as it has much better success rates than speech to text!

• It is impossible/difficult to know in advance what language a user will speak, so we recommend using a different phone number/TwiML app for each language that you intend to serve with this chatbot.

• All conversations start at the welcome_flow define in the channel. Callbot conversations never continue where they left off.

• To hung up on a user, simply reach a goto end.

• By default, there is a timeout of 5s on every hold. If the user does or says nothing, the conversation stops.

Components

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

• Text

• Question

• Audio

• Typing

• Wait

Callbots on CSML Studio also support an additional custom component, CallForwarding. This allows redirecting the user to a different phone number. This is very useful in a triage type of chatbots: when the request is qualified enough, you can simply redirect the user to the right person or service!

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:

Limitations

• For now, you can not create multilingual Twilio callbots as the language is set in the channels settings. However, this feature can be added upon request, so let us know if you need it!

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:

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!

Setup Twilio

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

Step 2: Configure the messaging webhook

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!

Text

Slack has partial markdown support in text components.

say "His palms are sweaty, knees weak, arms are heavy"
say Text("There's vomit on his sweater already, mom's spaghetti")
say "He's _nervous_, but **on the surface** he looks ~calm and ready~"

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.

say Typing(1000)
say Wait(1000)

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.

say Question(
  "Hi! My name is:",
  buttons=[
    Button("What?", payload="btn1"),
    Button("Who?", payload="btn2", style="danger"),
    Button("Slim Shady", payload="btn3", style="primary"),
  ]
)
hold
say "User selected: {{event}}"

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.

say Image(
  "http://placekitten.com/500/500",
  title="Nice kitten", // optional
  alt="this is a photo of a cute kitten", // optional
)

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.

say Video("https://cdn.csml.dev/customers/93bfb0df-fb6b-4ed2-87b0-8d93a09b0ad8/files/cbaa0959-fe58-4a2a-89c3-c414a1f38748/big_buck_bunny.mp4")
say Audio("https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3")
say Url("https://www.wikipedia.org/")

Carousel, Card

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

do card1 = Card(
  "The Marshall Mathers LP",
  subtitle="Release date: May 23, 2000",
  image_url="https://upload.wikimedia.org/wikipedia/en/a/ae/The_Marshall_Mathers_LP.jpg",
  buttons=[
    Button("Listen to this album", payload="marshallmatherslp1"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)
do card2 = Card(
  "The Slim Shady LP",
  subtitle="Release date: February 23, 1999",
  image_url="https://upload.wikimedia.org/wikipedia/en/3/35/Eminem_-_The_Slim_Shady_LP_CD_cover.jpg",
  buttons=[
    Button("Listen to this album", payload="theslimshadylp"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)
do card3 = Card(
  "The Marshall Mathers LP 2",
  subtitle="Release date: November 5, 2013",
  image_url="https://upload.wikimedia.org/wikipedia/en/8/87/The_Marshall_Mathers_LP_2.png",
  buttons=[
    Button("Listen to this album", payload="marshallmatherslp2"),
    Url("https://www.eminem.com/", text="Visit eminem.com"),
  ]
)

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

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

Input, Textarea

// the same works with Textarea()
say Input(
  title="Enter something below",
  description="This is a simple text field, and you can say whatever you want",
  placeholder="Whatever you want",
  submit_label="Submit",
)