How to Write Chatdown Markup

Chatdown is an extension of the Markdown language for generating mock chatbot transcripts. Here’s a simple example of a .chat source file:


bot: Welcome to SuperBot!
user: Hello, SuperBot! What can you do?
bot: I can help with many problems...

The transcript will replace ”user” and ”bot” with ”Tester” and ”SuperBot” respectively. A .chat source file consists of a header, where you define the aliases, and the conversation.

The Chatdown software is an open source command line application, created at Microsoft. It requires Node.js. The documentation on its website is the best place to learn how to use it. You can use just the features described there, or you can add the full power of Markdown to format the output.

Microsoft’s Bot Framework Emulator runs the transcript as a real-time conversation.

You can create a .chat file with any plain text editor. You then convert it to a transcript by running the Chatdown command:


The output goes to standard output, which you can capture to a file. Alternatively, you can specify an output directory, letting you process multiple files in one command:

chatdown *.chat -o ./chat_transcripts

Special features

Chatdown supports a number of features to enhance the transcript. You can add ”[Delay=500]” to indicate a delay in milliseconds, or ”[Typing]” to indicate the user is typing. The brackets are part of the directive. You can show users being added to or leaving the conversation with a directive such as ”[ConversationUpdate=MembersAdded=Dave]”.

A chat file can use card templates. They allow incorporating an image, audio, video, or other kind of card in the transcript. The card’s content can be in a separate file or at a URL.

The chat file can incorporate attachments. The attachment directive specifies a file or URL, and optionally a content type. You can use either a MIME type or one of the defined shortcuts.

[Attachment=images/sample.jpg "image/jpeg"]

Creating transcripts with Chatdown is a quick way to demonstrate how a chatbot is going to work. It lets you create as many scenarios as necessary.