CDML Manual

A CDML is a markup language that details the chat bots communication flow. The CDML files represents the conversation constructs that may be undertaken to dictate the flow of conversation. CDML stands for conversation Dialog Markup Language. It is in YAML format. 

The chat bot designer designs the conversation flow using CDML constructs.

A CDML file captures the fine elements of conversation in blocks of re-usable flow structures. A conversation takes place using 1 or more conversation flows.
The cdml file is constructed by the chat designer. Chat Studio can be great tool for this purpose. The Chat Studio provides features like 

<todo: verify>

The cdml file is validated and then it is used for deploying the chat application.

Building Blocks of Conversational Flow

Before starting to work on the cdml , the bot designer should have clear understanding of the conversation dialogues that is intended. The bot controls the conversation flow with the end user. With increased use of NLP, the end user will certain control over the conversation. The user’s information is processed to capture the intents and this intent takes the conversation to another  conversation flow. 

The conversation designer must identify the groups of conversation flow. Each flow captures or provides one set of information.

Building blocks

Let us have a look at the basic building blocks for StackChat conversation experience

There are more tools to enhance the experience

block structure

Persistent Menu

Persistent menu are the options available to the user at start. Its is sticky - it remains on the bot page. It is helpful to allow the user to navigate back during the conversation. It is usually the first menu available to the user. 

Persistent Menu is shown as clickable buttons at the Botton of the screen. On clients that do not support such menu, the menu is listed out the user.

Facebook Messenger


Web Client

CDML Constructs

Each of the constructs of the cdml file are detailed below:

cdml_version : 0.0.1

At the top there are 2 main constructs:


Optional. The version of cdml in use. Using the correct version will ensure use of the correct compiler.
<todo: backward compatibility. Availability of different compilers at the same time>cdml_version : 0.0.1


The bot represents the chatbot. It is the main construct. It contains the conversation flows and menu’s. Only one bot construct is supported in each cdml.

bot :
    name: BreakFastBar # Name of the bot
    version : 1.0.0
    format : chat

A bot supports the following elements


mandatory. Simple text to identify the bot.


version of the bot.


Array of tags that the bot is marked with. <TODO: examples>


mandatory. The format in which the bot is capable of communication. Supports values


This will be in persistent menu of the bot. Click here to view more specs


This is where we define conversational flows. There can be more than one flows. The conversation can go from one flow to another. It could branch out to another flow.

Click here to define flows