CDML - Conversation Design Markup Language

By Duncan Tweed on March 6, 2020

By Duncan Tweed

March 6, 2020

Conversation Design

We all dread unwanted and difficult conversations. Whether it be repetetive sales queries, product related FAQs, service inquiries, marketing and promotional distribution or just plain old bad news. The fact is these conversations are a reality of life, sometimes you just have to get on with things right? Well, sometimes, but we at Stackchat don't think they always need to be as such.

With the rise in popularity and in turn the capabilities of automated conversation, the world is seeing a rapid shift towards using chatbots and intelligent assistants as agents of a new wave of conversational engagement. These agents can help us all alleviate some fo the woes that come along with difficult and repetetive conversational experiences.

Conversations no longer need to be ad-lib, one off, and lost forever after they've been ha. With the advent of conversation automation, even those that see themselves as poor orators, will have the opportuinty to design meaningful, reproducable experiences that can be delivered at scale anytime anywhere.

Even better news for all of us is that today there are many different avenues available to create these conversations, all the major social media platforms and assistant technologies (alexa, google home) provide API's for us to consume and create chatbots.

So given the wide spread demand and availability of automated conversations, why are so many teams struggling to make good use of them or not using them at all?

Strong Foundations

While chatbots give us unrivalled flexabilty, they are also multi-faceted. They aren't just made up of our good intentions and clever words, but instead consist of complex API's and network requests that bare little reminder or connection to the high level problems they are trying to solve in the real world.

In a world where chat is ubiquitous and users/customers hold high expectations of the outcomes they get from an automated conversation, teams need to be flexible and able to move quickly when designing different conversational experiences without implementation concerns tying them down or hindering their veolcity to respond to their target audiences requirements and demands.

At Stackchat we realised early on that many of the teams and individuals that were most interested in introducing a chatbot or digital assitant into their product/service, were often not the team responsible for it's construction and maintenance.

To briefly summarise the problem space so far, and why some teams are not fully utilising their automated conversation capabilities to their highest degree's or in many case not at all:

  • Implementation concerns are complex and require technical expertise.
  • Teams need to move quickly but technical concerns, or poor internal management/cross communication slows down their abilities to do so.
  • Bots become difficult to reason about at scale and most teams or chatbot service providers lack the tooling to deal with this.
  • Teams that would like to have a chatbot, are often not directly involved with operations of their bots.

We knew when we created Stackchat that if we couldn't address these core problems that conversation designers were having, we'd be unable to bring about our goal of making chatbots and intelligent assistants more accessible.

We believe that there shouldn't be any reason that non-technical individuals aren't able to design and maintain their own customer conversations, regardless of how large they become.

These are foundational level questions, to build a solid product we need to make sure that our foundations are strong, we needed to solve these problems.

Introducing CDML

Introducing a Universal langauge for creating conversational experiences (C)onversation (D)esign (M)arkup (L)angauge or CDML for short. CDML is our silver bullet that addresses the aforementioned issues. If you can imagine that HTML/XML is the scaffolding language of the internet, then CDML can be seen as the scaffolding language of conversation design. It's intuitive, readable and easy to learn.

Sample CDML from the Stackchat Studio tutorial bot.Sample CDML from the Stackchat Studio tutorial bot.

The beauty of CDML really shines through it's nature of being simple, yet expressive.It allow for those with little to no previous expsoure to it, to gain a rapid understanding of what is happening in any conversation without the need for extensive material referencing or documentation look ups. For those already familiar and experienced with CDML the opportuinity exists to rapidly iterate irrespective of how large a conversation grows.

A great example of CDML's simplicity recently came from an internal query that originated with one of our own clients. After creating a chatbot for them that responds to complex queries through both text and voice with results of products they have available for purchase, they wanted their social team to review the standard responses of the bot in order to make sure they aligned with their brand guidelines.

For us this was as simple as copying across their bots CDML and sending it through to them as you would any other document, within the Stackchat Studio our bot authoring platform, you have the option at anytime to open up an editor to review and manually edit the underlying CDML, so providing them with what they want was as simple as logging in and copy pasting their bot into an email.

Shortly after we had sent them the CDML, their team was able to quickly review it, make edits and return them to us. Despite no formal training, nor us having to supervise them through the process.

As mentioned before, CDML is a universal language and it is not something we created to keep as a proprietary in house solution. The Stackchat Studio is a good example of this. The Studio is comprised of several services, one of those core services is the 'bot-builder' suite. This entire suite is built around reading CDML which could come from anywhere and turning it into an editable user interface on the fly.

Having used CDML in house for some time and knowing how well it works, we are looking forward to releasing new tools to make working with CDML even more simple and engaging.

The CDML snippet on the left generates the interface we can see on the rightThe CDML snippet on the left generates the interface we can see on the right

There are several beneficial side effects of using CDML as a formalised language for defining conversation structure within the engineering space that are also worthy of noting.


Revisioning is hard, especially for complex services made up of many moving parts. CDML is simply a text file that is the source of truth for any given conversation it represents. That means to revision a bot, all that needs to be tracked is the CDML. The only thing that you need to decide when it comes to revisioning if you're using CDML, is to what level do you want to provide historical revisioning, you can track every single change ever made or only save changes to versions of the bot that have been published. Unlike traditional API services where updates result in server side calls which are difficult to replay, or undo or keep track of, by using CDML, easy revisioning strategies come for the ride.

Realtime Edit Tracking

This feature is discussed in further detail another blog post, but it still worth mentioning here. Collaborative editing is a difficult feature to implement, however tracking changes to just a single file greatly simplifies the process as you only need to pass down the updates or a fresh copy of that file instance to all connected clients to ensure everyone has the latest copy. This is how the Stackchat Studio keeps clients up to date.


CDML is platform and service agnostic, it doesn't care what third party or in house solutions you use to accomplish non-linear conversation events such as intent/entity extraction or other NLU/NLP related tasks, as long as your service is defined within the expected parameters of CDML then the CDML is valid, remember CDML is a scaffolding layer, it is not the actual implementation or service.

Platform Independent

It might already be obvious to you, but CDML is platform independent, if you want to create a service that consumes CDML, it doens't matter what how you implement it or what tooling you build around it, CDML is by design platform independent.

Gives conversations creators the opportuinity to think of their conversation in a mappable and logical fashion, instead of an assembly of loose ideas in their head or platofrm specific operations.

I hope that this post has managed to illustrate the usefulness of a CDML as tool for authoring automated conversations and if you were thinking of creating your own bot or guided conversation to consider the benefits of using CDML to create and structure that conversation.