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]