Skip to main content

Crash Course

user "How can I get started really fast?"
bot "Check out the cheat sheet below"

If you have prior coding experience, or if you are a fast learner, this course is for you.

Basics

Conversations are a symmetrical exchange of messages between a user and a bot.

user ...
bot ...

Message names should be short and descriptive.

user express greeting
bot express greeting
bot offer to help

Related exchanges are grouped into flows. Flow names should also be short and descriptive.

define flow welcome
user express greeting
bot express greeting
bot offer to help

User message definitions have multiple examples for training.

define user express greeting
"hi"
"hello"
...

Bot message definitions have at least one example (multiple ones for variation).

define bot express greeting
"Hey there!"

define bot offer to help
"How can I help you?"
"What can I help you with?"

For quick prototyping, you can use unnamed flows and inline bot messages.

define flow
user express greeting
bot "Hello! How are you today?"
Example

Check out the following example model

Naming conventions

Following a clean and consistent naming conventions makes your colang model easy to work with.

User messages

# User asks a question and expects an answer
define user ask ...
...

# User provides some information
define user inform ...
...

# User needs something e.g. a booking, a cancellation
define user request ...
...

# User expresses their feelings
define user express ...
...

# User comments about something
define user comment ...
...

Examples:

define user ask opening hours
"When are you open tomorrow?"
"What are your opening hours?"
...

define user inform account number
"My account is 123456."
"The account id is 123."
...

define user request refund
"I need to return a product I bought."
"I would like to get a refund on my order."
...

define user express thank you
"Thank you!"
"Thanks!"
...

define user comment duration long
"This is talking too long."
"That is a very long time to wait."
...

Exceptions

For user messages that are very frequent, shorter names can be used.

define user affirm
"Yes"
"Of course"
...

define user deny
"No"
"Not really"
...

Bot messages

# Bot asks a question and expects an answer
define bot ask ...
...

# Bot provides some information
define bot inform ...
...

# Bot expresses their feelings
define bot express ...
...

# Bot requests something from the user e.g. rephrase
define bot request ...
...

# Bot confirms information for the user
define bot confirm ...
...

# Bot makes an offer to the user
define bot offer ...
...

Examples:

define bot ask name
"What is your name?"

define bot inform identity verified
"Your identity is now verified."

define bot express apologies
"I am sorry."

define bot request rephrase
"Can you please rephrase?"

define bot confirm capability refund
"I can help with refunds."

define bot offer refund choices
"Account credit, gift card, paper check or credit card?"

Flows

For user-initiated flows (starting with a user message), the name should describe the interaction.

define flow handoff  
user request handoff
bot express acknowledgement and inform handoff in progress
...
define flow order refund  
user request refund
bot confirm capability refund
...

For bot-initiated flows (starting with a bot message or action), the name should describe the high-level action.

define flow authenticate user 
bot inform authentication required
bot ask if ok
...

define flow pull up account
bot ask name
user inform name
...

Conversation paths

A conversation can take various paths, e.g., happy paths, repair paths, explanation paths.

Branching

You can branch the conversation in multiple paths, based on the user message.

define flow authenticate user
bot inform authentication required
bot ask if ok

when user deny
bot inform unable to continue
bot offer handoff to human
...

else when user affirm
bot ask account number
user inform account number
...

Interruptions

Flows can interrupt each other and handle different parts of a conversation.

define flow question about authentication
bot inform authentication required
bot ask if ok
user ask why
bot comment about security compliance
bot ask if ok resume authentication

For example, the highlighted section below is handled by the flow above:

bot "But first, I need to verify your identity."
bot "Is this ok?"
user "Why do you need that?"
bot "We need to authenticate users before giving out sensitive information."
bot "So, can we continue?"
user "Yes, that's ok."
bot "What is your account number"

Sample flows

You can write sample flows for documentation purposes.

define sample flow refund request
user "Hello!"
bot "Hey there!"
bot "How can I help you?"
user "I have a problem with my refund"
bot "Sure, I can help with your refund."
bot "What is your account id?"
user "It's 1234"
...
warning

This documentation page is still being written. The sections below will be available shortly.

Entities

Variables

Events

Tests

Actions

Objects