To make it really easy to publish your chatbot, CSML studio provides a full-featured webapp so that you can easily integrate your chatbot into any existing project. This is the simplest way to deploy your chatbot at scale!
By default, the webapp channel does not include any specific context about the conversation (see the _metadata object documentation). In some cases, it can be useful to load the webapp (or chatbox) with pre-existing metadata.
Some common scenarios:
the bot is loaded in a website where the user is already known: in that case, we may be interested in injecting the user's context (name, email...) inside the conversation.
the user is authentified on the parent website: in that case, we may want to inject an authentication token into the user's conversation for subsequent calls.
the same bot is used across several websites and we want to know which website the user is currently visiting: in that case we can inject a unique website identifier into the conversation.
The injected data is available in the _metadata global variable, available in every flow.
The code of the example above is:
To add custom metadata in a webapp, simply add the encoded (with javascript's encodeURIComponent function) JSON string of the metadata you want to inject to the query parameters of the webapp's URL. The URL of the webapp in the example above would be:
You can change the appearance of the webapp by visiting the Appearance tab of the webapp 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
The settings panel has a few options to allow you to configure the webapp. Each webapp must have a name, and you can also add an optional description and logo. If needed, you can also link to your own terms and conditions as well.
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!
If you want your users to be able to quickly launch any of your flows, you can use the menu, by adding shortcuts to any of the existing flows. For each flow, you must define a label to make it easily recognizable by your users.
In mobile view, the applications menu will show at the bottom of the screen and slide up when activated:
You can launch a specific flow (and step) instead of the default Welcome Flow when loading the webapp by providing a ref parameter in the webapp URL.
There are two ways to use Ref parameters to redirect to flows. You can either configure them in the channel's settings page by adding connections between custom Ref parameters and a target flow:
Or you can use the following special syntax:
The main advantage of the second syntax is that you can generate the links on the go; however, the first method is more flexible as you can easily change where a link is redirected even after it is created, and the content of the Ref parameter is entirely customizable.
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 webapp's configuration panel:
The request that will be performed by the webapp will be as follows:
Your endpoint must return results within 5 seconds as an application/json content-type, formatted as an array of maximum 5 results containing a title, optional highlighting matches, and the corresponding payload.
When a user selects a result, it will behave as a button click where the text is displayed and the payload is sent to the chatbot.
If an autocomplete endpoint is set, it will be enabled by default. However, it can be disabled or reenabled dynamically in your CSML script:
Autocomplete status is not persisted across page reloads. When reloading the page, this will always be set to true by default!
The webapp channel also comes with a configurable website plugin (called the Chatbox) that can be added to any website by adding a single line in your source code. The Chatbox will then appear as a small bubble in the bottom-right corner of your site for every visitor.
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):
Once this is done, a chat bubble will appear as follows on every page where that code is included. Clicking the chat icon will open the chatbox:
The Chatbox lets you configure a custom popup message as well as up to three Quick Action buttons to help you engage more actively with your customers. If both fields are left empty, only the blue chat icon will appear. You can also configure only a popup message or only the action buttons! You can find these configuration options in the Chatbox settings, one of the Web Chat configuration panels.
When configuring Quick Action buttons, you must provide both a title and a payload. The payload can be any string that will be interpreted by CSML. In the example below, those buttons contain a simple payload that match corresponding flows. You can also use an AI Rule trigger as a payload!
By default, the chatbox will be displayed on the right side of the screen. To display the chatbox on the left instead, simply add data-position="left".
For example: data-webapp-metadata="%7B%22email%22%3A%22jane.doe%40company.com%22%7D"
You can configure a custom image to be used as the chatbox 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"
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:
Force the chatbox 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!
Set the inner webapp's ref param to trigger a specific flow or step
The Text component of the Webapp channel also supports some basic Markdown:
Obviously, Wait is also supported (it simply does not display a typing indicator or anything for the given duration).
If you need to retrieve a specific data when clicking on either button, use the payload argument of the Button component:
The Webapp channel also supports single Button components. However, as cross-channel support for single buttons is not guaranteed, we encourage you to use the standard Question component instead, with a title.
In some cases it may be desirable to temporarily disable the user input to force the user to select one of the options without letting them type anything.
Please note that if the page is refreshed, the user input will go back to being enabled by default even if it was first disabled.
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.
Standard limitations apply: if the end user is not logged in to a valid spotify/deezer/soundcloud account, only 30s will be playable in the audio component.
For full control over the clip, prefer using a standard mp3 file 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.
A Carousel is essentially a collection of Card elements A single Card will display as a Carousel of 1 element. Each Card can have a maximum of 2 Button elements.
The cards themselves can be made clickable by adding an optional default_action Url() parameter:
The carousel can also automatically navigate horizontaly by adding the optional autoplay parameter (which defaults to false):
This component will display a rich calendar in the webapp. By default, when passed with no argument, a simple single-date datepicker will appear:
Optional parameters allow to set a min_date and/or max_date (by unix timestamp, in milliseconds) or an input_mode to accept single (the default) multiple or range inputs by the user:
The event value of a Calendar input will be comma-separated values of all user inputs. Also, event.input_mode will be set to the mode of the requested calendar, so that you can differenciate between single, multiple and range modes when receiving values.
To gain some control over what a user can enter in a form (for example, if you need to make sure they only enter an email address or a valid number when required), you can also use the Input component.
There are several variants of input fields: email, text, textarea, number and password. By default, inputs are type="text". All parameters are optional, and the basic usage is as follows:
A completely bare say Input() component will result in this simple, empty text input:
Inputs with type="number" can have some different parameters, just like HTML inputs (all are optional as well):
Display a radio buttons component:
If you want to let users select multiple options, the Multiselect() or `Checkbox()` components are a great solution. Users will be able to select any number of options in the given list. You can force a min and max number of choices, or if required=true, it means that at least one option must be selected to continue.
Both the Multiselect and Checkbox components work exactly the same, only the display will be different. Try both to find out which one suits you best!
When several options are selected, you will receive a comma-separated list of the corresponding payloads (not necessarily the button's title!), in the order they were selected by the user. In the case above, you would receive:
Like the Radio component, the Dropdown lets users pick an option from a list:
You can also add LaTeX inline in any standard text like by encapsulating it inside {latex}...{/latex} tags:
You can display a simple signature field i.e to collect user consent and receive it as a png file.
You can use the OAuthRequest component as specified here:
To create a webapp channel, click on the channels menu then on create new channel.
Click on Webapp, add a name and a description (you can change it later), then click on Submit.
After a few seconds, your webapp is created and ready to use!
There are two ways to use a webapp: either by visiting the link at the top, or by adding the embed link for integrating it into your existing website. It works on mobile too!
Several configurations are available as to maximize compatibility across browsers.
To add custom metadata in a chatbox (), you need to add a data-webapp-metadata attribute to the chatbox initialization script tag that contains the encoded (with ) JSON string of the metadata you want to inject.
Quick replies are similar to Questions, where the buttons are removed from view once the user has selected one of them. In a majority of scenarios, you should prefer QuickReplies over regular questions, especially when you don't want the user to be able to scroll up and select one of the buttons after they have made a first choice. Questions should be used when a button is used as a trigger to a given flow (as configured in the bot's ).
Try this bot:
Try this bot:
Try this bot:
You can check this reference about the minlength and maxlength parameters:
You can check this reference about the min and max parameters: .
To learn more about the inputs with type="password", read the documentation about secure inputs (hold_secure):
is a popular language that lets you write (among other things) complex math formulas. The webapp and chatbox include to support this language natively with a custom component:
You can find more examples of supported formats on the KaTeX documentation: . Please keep in mind that backslashes (\) must be escaped properly in your code!
Try this bot:
Try this bot:
