Custom components are clearly an advanced feature of CSML. Unless you are missing specific features with the default capabilities of standard CSML message components, you probably will never need to learn more about this topic!
Feel free to skip to the next section 😉
Under the hood, all message components are created using a JSON-based templating system to describe how the component should behave, what properties it should accept, which are required or optional, their type, etc.
For instance, here is the low-level code to generate the simple Text() component:
Which outputs the following JSON payload when used in a CSML flow:
Obviously, more complex components are also possible. Here is an example with the standard Button() component:
You will notice the use of the $_get keyword. This function retrieves the value of the given parameter and sets if in place. So for example, in our example, the button's payload will be set to what the developers sets, or by default to the value of the title parameter. Same thing goes for the accepts property, which results in the following output:
In addition to the standard components, you can also add your own custom message components using the same templating format.
Each component is made of a list of params, that all have the same structure:
if set to true, will display an error when the value is not set in the flow
describe the type of the parameter to accept
Null
Bool
Number
String
Array
Object
default value to set on the object
values to add to the object in all cases (even if a default value is set)
$_get: will inject the value of the given parameter
$_set: will set the field to a specific value
In some cases, you may want to specialize your chatbot for one specific channel, which has some complex formats available that you want to make easier to use. For example, CSML Studio has a QuickReply custom component, which is a quicker way to create quick replies, which are features of Messenger, Workplace Chat and the Webapp channels.
If you are making a specialized chatbot for a specific channel, consider using custom components to make your life easier!
There are two ways to import your own custom components in the CSML Engine and use them in your flows.
as native components by saving your all your custom component files in files in a given directory, and set the COMPONENTS_DIR environment variable in your CSML Engine. In that case, the name of the component will be the name of the file (without the extension).
as local components by adding a list of custom components to your chatbot's configuration when calling the engine. In that case, you should add a custom_components parameter to your bot description with an array of key/value objects where the key is the name of the component and the value its definition.
Native components and local components behave exactly as standard components. The only difference is that local components are used with a prefix (Component.MyComponent) in your flows, whereas native components can be called directly (MyComponent). This allows you to define different components per bot for the same engine instance, while being able to use common components across all your chatbots. Similarly, local components are easier to share with other users of your chatbots as they can be packaged together.
CSML message components all have a matching message format for client use in regular JSON. They can be extended by adding additional properties to the content wrapper.
Component payloads can be included into one another seamlessly. For example:
CSML is able to handle many types of messages by default.
To send a message to the end user, simply use the keyword say followed by the message type you want to send.
You can style text using Markdown. Some channels however only partially support Markdown (Messenger for example only allows bold, italic, strikethrough, but not tables), so don't get too fancy there.
Below is a list of default valid message components, which are automatically converted to nicely formatted messages for the channel in which the user is talking with the bot.
name
description
fallback
Text(string)
Output a simple string (with no styling attached). This is also the default type, alias of say "string". This component supports Markdown on channels that allow text formatting.
Wait(number)
Wait number milliseconds before sending the next message
Typing(number)
Display a typing indicator for number milliseconds
Wait(number)
Url(string, text="text", title="title")
Format string as the URL. Optionally, the text and title parameters can provide a way to make "nicer" links, where supported.
Text(string)
Image(string)
Display the image available at URL string
Text(string)
Video(string)
Display the video available at URL string. Supports Youtube, Dailymotion and Vimeo URLs, or mp4 and ogg.
Url(string)
Audio(string)
Display the audio available at URL string. Supports Soundcloud embed links, or mp3, wav and ogg.
Url(string)
Button(string)
Display string inside a clickable button
Text(string*)
Question(title = string(, buttons = [Button]))
Display a list of buttons with a header of string. Title parameter is optional.
Text(string) + list of buttons
Card(title="string", buttons=[Button], image_url="string")
Display nicely formatted content in a Carousel component (on supported channels). Only title is mandatory.
Question(title, buttons) or Text(title)
Carousel(cards=[Card])
Display a list of Cardcomponents in a carousel (on supported channels). The cards parameter is mandatory.
Components may receive additional optional parameters to accommodate the needs of certain channels.
For example, in the Messenger channel you can add a button_type="quick_reply" parameter to the Question component to provide a different type of buttons.
A conversation with a chatbot is not very different from a human-to-human dialogue: sometimes the user talks, sometimes the bot talks.
CSML provides a solution when you need the chatbot wait for the user's input: using the hold keyword, the chatbot will remember its position in the conversation and simply wait until the user says something, then continue from there.
When receiving an event from an end-user, the CSML interpreter will try to:
match it with a new flow,
or consume it in the existing conversation,
or trigger the default flow as defined in the bot settings,
by order of priority.
CSML Events are made available in the script when a step is triggered by a user's input. The event object is a complex structure which contains a lot more than just the string that was typed by the user. It contains a lot of information that is used by the CSML interpreter, for example the custom button payload to match a list of choices offered to the user. This makes it easy to handle both a click on a "OK" button or the user typing the word "yes".
By default, events are only expected when:
the flow was just triggered, the current step being triggered is start
the bot asked something to the user, and is waiting for the user's input at the same step
In those cases, a local variable, event, is made available, with the content of the user request. When no event is available, event is set to NULL.
The maximum theoretical size of a say payload is 16KB. However, each channel will have different limitations depending on the type of component. For a Text component for example, most channels are limited to a few hundred characters.
Please refer to each channel's official documentation to find out the practical limitations of each component.