co-nlg
warning
This documentation page is still being written.
This module defines how to model bot messages that are sent back to the user.
Simple Messages
Bot messages can be defined directly in a flow at the point where they are needed:
some_flow:
...
bot "How are you?"
...
Predefined Messages
If a message is used in more than one place, it can be defined separately:
define bot ask how are you
"How are you?"
flow_1:
...
bot ask how are you
...
flow_2:
...
bot ask how are you
...
tip
Notice that the name of a bot response can contain spaces. This will enable the use of advanced matching features. See the "Advanced Usage" section below.
If more than one example utterance is included in the definition of a bot message, one of them will be chosen randomly every time:
define bot ask how are you
"How are you?"
"How is your day going?"
"Whats up?"
Inline Syntax
warning
Support for this is deprecated and will be removed.
It is possible to create a predefined bot response directly in a flow and reuse it in other places. Just add the name of the utterance in front of the actual text. Also, note that you can put the text on the next line as well, by increasing the indentation level.
some_flow:
...
bot how_are_you "How are you?"
...
bot inform order placed
"Your order has now been placed"
...
bot ask confirmation name with $name="John"
"Is your name, $name?"
"Is this your name: $name?"
"Can I confirm that your name is $name?"
Using Context Variables
Context variables can be included in bot messages:
some_flow:
...
bot "How are you, $name?"
...
Predefined Messages and Variables
Predefined bot responses can also include context variables:
define bot ask how are you
"How are you, $name?"
define bot inform opening time
"We're open from $opening_time on $date."
When using a predefined bot response, we can pass the values to use as parameters:
some_other_flow:
...
bot ask how are you
$name: "John"
some flow:
...
$opening_time = "9am"
$date = "November 22nd"
bot inform opening time for $date, $opening_time
Parameters are first matched by name and the remaining parameters are matched positionally.
You can also specify explicitely the value for each parameter:
some flow:
...
$some_time = "9am"
$a_date = "November 22nd"
bot inform opening time for $date=$a_date, $opening_time=$some_time
Conditional Bot Responses
It is possible to take into account the context and decide on what message to use. For example:
define bot greeting
if $system_time < "12:00"
"Good morning!"
"Morning'"
else if $system_time < "17:00"
"Good afternoon!"
else
"Good evening!"
"Evening there!"
Multi-Language Support
caution
Not yet implemented.
language en
define bot ask how are you
"How are you?"
language fr
define bot ask how are you
"Comment ça va?"
flow_1:
...
bot ask how are you
...
Meta-Data
In addition to the bot response, you can also send additional meta-data (like headers for an HTTP request). The meta-data is usually used by the channel integration. For example, to customize the speech gathering behavior for the Twilio Integration you can set the $twilio_config
meta-data.
bot "What is your PIN?"
set $twilio_config to
speechModel: "numbers_and_commands"
speechTimeout: 5
hints: "1234, the PIN is 0000, 0, 1, 2, 3"
bot ask user pin
set $twilio_config to $twilio_pin_config
The meta-data can also be set directly on predefined bot responses. If the meta-data is included in a conditional branch i.e. after an if
, it will be used only for that branch.
For example, below we set the $twilio_config
meta-data to some name hints from the context variable $twilio_name_hints
, but only when the user is calling.
define bot ask name
if $user_is_calling
set $twilio_config to $twilio_name_hints
"Can I have your name?"
else
"Can I have your name?"
Widgets
For text-based channels, there is support for quick replies and snippet replies.
Quick replies
For channels that support quick replies i.e. buttons that the user can click to send back predefined messages, they can be modeled as shown below:
bot "How are you?"
quick_replies: "good", "bad"
Snippet replies
Similarly to quick replies, snippet replies help the user input faster longer phrases with multiple dynamic elements. For example:
bot "Great, please help me with the following information"
snippet:
id: text_field_config
text: "The <name> field should be <editable> and have the color <color>."
params:
name: ""
editable: ["editable", "not editable"]
color: ["red", "green", "blue"]
user inform with $editable, $color
The first element in the list of possible options for a parameter is the default value. If you don't want any option to be selected initially, include an empty string as the first option.
note
Currently, only "select" elements (i.e. enabling the user to choose from a list of pre-defined values) and "text" elements are supported in snippets.
Objects
Objects can be included in bot messages.
Templates
define template Speaker
title: $name
subtitle: $title
image: $avatar_url
buttons:
- title: Contact
url: $linkedin_url
Formatters
The default formatter for an object is to use the name
or text
property.
Additional formatters can be specified as shown below:
bot "You have an appointment $appointment_date|relative"
DateTime
DateTime
objects have the following available formatters:
Format | Examples |
---|---|
default | "21 Oct 2021 4:30pm" |
friendly | "Oct 21st at 4:30pm" |
relative | "tomorrow at 4:30" |
Advanced Usage
Following a consistent naming convention for the bot responses enables us to write generic flows that can take advantage of that. Let's take an example like offering the user a set of choices:
bot "What color do you prefer: red or blue?"
user "The first one."
...
bot "What hour would work best for you: 9am or 11am?"
user "The first one."
This is a common pattern, especially in voice interaction. Ideally, we would want to implement this behavior only once in our bot, and use it in every instance. The following is one possible solution:
...
bot offer choices colors with $colors=["red", "blue"]
"What color do you prefer: $colors"
user choice
bot "$choice is a great color!"
...
bot offer choices time with $times=["9am", "11am"]
"What hour would work best for you: $times?"
user choice
bot "$choice it is!"
...
define user choose_by_number
entity $number as number
"the $number one"
define flow infer_choice_by_number
bot offer choices with $choices
user choose_by_number with $number
# We turn the number into a choice
infer user choice
$choice=$choices[$number]