Skip to main content



This documentation page is still being written.

define user hello
"hey there!"


Every message from the user needs to be interpreted by the bot in order to determine what the user meant and what to do next. The result of the interpretation is represented by the intent of the message and, optionally, by one or more entities. The intent is simply a category of user messages which is defined at design time. The entities represent specific bits of information that are included in the message e.g. names, locations, numbers, dates, etc.

define user INTENT_NAME

"example simple utterance"
"example utterance with $ENTITY_NAME"
define user affirm
"of course"

Entity types

The co-nlu module defines the following set of commonly used entity types:

numberAn integer or float number expressed both using digits and letterse.g. 2, 15, 250.2, thirty two
dateRepresents a datee.g. today, tomorrow, 12 June
booleanRepresents a boolean valuee.g. True, False

Regular Expressions

Entities that should match a regular expression can be defined as follows:

define user inform ping
entity pin as regex:"\d\d\d\d"

"it is $pin"
"PIN: $pin"

Lookup types

define lookup refund_option
"account value"
"gift card, gift"
"card, credit card, debit card"
"check, paper check"
define user inform
entity $refund_option as lookup:refund_option

"I want a $refund_option"


A special intent defined by this module is called inform and it should be used to model user messages where only the mentioned entities are important rather than the intent. For example, when the user is asked to choose between three options, we're interested just in the choice they make.

define user inform
entity account_id as number

"my account id is $account_id"

Entity values

define user inform $order_status="unknown"
context "order_status" in $expected

"i don't know"
"i dont think it has shipped"
"I haven't received it yet, but my account doesn't show a shipping status."
"It looks like it hasn't been shipped, but I don't see anything written anywhere"



Contextual Examples

Certain expressions can mean different things when said in different contexts. To model this, you can specify the context for examples as shown below:

define user inform order_status out_for_delivery
context "order_status" in $expected

"out for delivery"
"it's out for delivery"

In the example above, the expressions "out for delivery" and "it's out for delivery" are interpreted as inform order_status out_for_delivery when the context expression "order_status" in $expected is true. You can use any valid expression to define the context.


As an implementation detail, each expression will be translated into a separate feature that will be used by the machine learning model.

The general syntax for contextual examples is the following:

define user some_intent
"non contextual example 1"
"non contextula example 2"

"contextual expression 1.1"
"contextual expression 1.2"

"contextual expression 2.1"
"contextula expression 2.2"


Expected Intents

A frequent use for defining the context of an example is using the intents that are expected at that point in the conversation. For this, the contextual expression can be the user intents themselves as shown below:

define user inform pin_number
entity pin_number as number

"my PIN is $nhs_number"

in the context of user inform pin_number

In the example above, if we're in the context of expecting the user to provide a PIN i.e. there is a flow at a user inform pin_number location, then any number provided at that point will be interpreted as a PIN. In a different context, a number can be interpreted as an account ID, for example.


The in the context of syntax is just a more verbose and readable variant for simply saying context. Both can be used interchangeably.