Introduction to Natural Language Understanding

A Natural Language Understanding (NLU) service matches text from incoming messages to training phrases and determines the matching "intent". Each intent may trigger corresponding replies or custom actions.

For some intents, Natural Language Understanding services may also extract particular data fields from the message (e.g. date/time or location), and normalize the value of the field. Telerivet provides many built-in field types, and you can also add custom field types by defining lists of synonyms and corresponding normalized values.

For each message that triggers a Natural Language Understanding service, Telerivet saves the intent ID as a custom message variable (by default, vars.intent). Any normalized data fields are also saved as custom message variables (e.g. vars.date, vars.price_currency, vars.price_amount, vars.foo). 

You can configure certain intents to trigger only in certain contexts, such as a follow-up intent where the contact can send YES or NO after triggering another intent. Intents can also refer to data fields collected earlier in the conversation using custom state variables (e.g. state.vars.date, state.vars.price_currency, state.vars.price_amount, state.vars.foo).

Supported Languages

The following languages are supported for Natural Language Understanding services:

• Bengali
• Chinese (Simplified)
• Chinese (Cantonese)
• Chinese (Traditional)
• Danish
• Dutch
• English
• Filipino
• Finnish
• French
• German
• Hindi
• Indonesian
• Italian
• Japanese
• Korean
• Malay
• Marathi
• Norwegian
• Polish
• Portuguese
• Romanian
• Russian
• Sinhala
• Spanish
• Swedish
• Tamil
• Telugu
• Thai
• Turkish
• Ukranian
• Vietnamese

Enabling the Natural Language Understanding Feature / Pricing

The Natural Language Understanding feature is disabled by default. To request access to the Natural Language Understanding feature and request pricing, contact us at support@telerivet.com . 

Triggering a Natural Language Understanding service will incur a usage fee each time a message is processed by the service. Usage fees will appear in the account's transaction history as "Natural language intent detection".

If the organization's Telerivet account has an insufficient balance, NLU services will trigger an error and will stop processing messages until the account has sufficient balance.

Adding a Natural Language Understanding Service

When the feature is enabled for your account, Natural Language Understanding will be available when adding a new service on the Services page:

When adding a Natural Language Understanding service, you have the option of triggering the service when a new message is received, or manually triggering the service for a message:

To use a manually triggered service, you would also need to create a Custom Actions service with a "Trigger service for message" action. If necessary, you can change the service trigger after creating the service under "Advanced settings".

When adding a new service, the first step is to choose a language and click "Initialize Agent". The language cannot be changed later (except by copying the service):

Defining Intents

When initializing a new agent, two default intents are created:

• input.welcome detects common greetings and asks how the agent can help
• input.unknown is a “fallback” intent that handles all other messages by asking the contact to restate their question.

Normal intents are indicated with a blue circle, while fallback intents are indicated with an orange square.

Intents are shown in a table with columns for the intent ID, variable names for data fields, number of training phrases, number of replies, number of custom actions, and last updated time. Some of these columns will be hidden if no intents have any values for that column.

To add a new intent, click “Add intent”. To edit an intent, click the intent ID.

When editing an intent, you can edit the intent ID, training phrases, replies, and add custom actions. When adding training phrases, typing Enter will add a new training phrase. When adding replies, Enter will add a new line within the same reply. Typing Backspace on an empty item will remove that item.

A character count is shown for each reply, and the Variables link lets you view and insert variables into replies. 

Any custom actions are displayed at the bottom:

To delete an intent, click the intent ID, then click “Delete intent”.

For each message that triggers a Natural Language Understanding service, Telerivet saves the intent ID as a custom message variable. By default, this variable is named vars.intent. You can change this variable name if necessary by clicking “Advanced settings” and editing the Intent ID Output Variable.

Defining Fields to Extract Data from Messages

To extract data from messages, click “Add field” when editing an intent, then enter a variable name and select a field type. Some field types set multiple values using the variable name as a prefix. In this case, each variable name and value is documented next to the Field Type. For example, if the Variable Name is “interval” and the Field Type is “Date Interval”, the service will set the custom message variables vars.interval_start and vars.interval_end, which you can use when sending replies:

Above the replies and custom actions, Telerivet shows a list of all custom variables set from the fields of that intent.

For each field added to an intent, there must be at least one training phrase containing the field's variable name in curly brackets as a placeholder, e.g. {interval}. If some training phrases do not contain all fields, it is possible for the intent to be matched even if all fields are not specified.

Required Fields and Prompts

Certain fields can be configured as required, and you can specify custom prompts if the required field was not detected in the incoming message:

If a field is optional (i.e, not required), Telerivet could trigger the intent's replies and custom actions even if a value for the field was not detected in the incoming message. However, if an intent has required fields, the replies and custom actions will only be triggered after all required fields are provided.

If a required field has multiple prompts and a value for the field was not provided, one of the prompts will be sent at random. If a required field has no prompts, a default prompt will be sent based on the variable name.

Built-In Field Types

The following field types are available in Telerivet by default:

• Date/Time
• Date
• Date Interval
• Time of Day
• Time Interval
• Number
• Number - Cardinal
• Number - Ordinal
• Integer
• Number Sequence
• Flight Number
• Area
• Currency Amount
• Length
• Speed
• Volume
• Weight
• Data Size
• Percentage
• Temperature
• Duration
• Age
• Currency Name
• Unit - Area
• Unit - Length
• Unit - Speed
• Unit - Volume
• Unit - Weight
• Unit - Data Size
• Address
• Zip/Postal Code
• Country
• Country Code
• City
• State/Province/Region
• Airport
• Location
• Email
• Phone Number
• Person
• Color
• Language
• URL
• Any Input

Note: Some field types may not be fully supported in certain languages.

Custom Field Types

You can also define your own custom field types. When editing fields for an intent, custom field types will be prefixed by “Custom - ” in the drop-down list.

Custom field types are displayed below the intents in a table with columns for the name of the field type, number of values, and last updated time.

To add a custom field type, click “Add custom field type”. To edit a custom field type by clicking the Field Type. 

You can change the name of the Field Type, and add one or more values. For each value, you can specify a reference value and add one or more synonyms using the “tag” input. The reference value is automatically added as the first synonym.

To delete a custom field type, click the field name, then click “Delete custom field”.

Creating Context-Sensitive Intents

Many Natural Language Understanding services require having intents that only trigger in certain contexts, such as an intent where the contact can reply "yes" or “no” to confirm something from a previous intent.

When editing an intent, the context for each intent can be configured at the top right. The context is an arbitrary string ID that can contain letters, numbers, and dashes.

Intents can activate/deactivate contexts using the new "Add context" and "Remove context" actions, which are available when adding a custom action (under "Advanced"). The "Add context" action lets you specify how many messages the context will remain active.

Since "Add context" and "Remove context" are custom actions, you can validate user input and perform API calls before adding or removing a context. If necessary, an intent can trigger multiple "Add context" actions with different context IDs.

Follow-Up Intents

For some use cases, you may want to send a simple prompt after an intent, such as asking the contact to reply “yes” to confirm. For common cases like this, Telerivet has a simpler way to configure intents so that you don’t need to configure contexts and add training phrases manually. 

When editing a service, each intent has an arrow icon on the right which allows adding various different kinds of follow-up intents:

Depending on the type of follow-up intent selected, Telerivet adds pre-configured training phrases for the current language:

When a follow-up intent is added, Telerivet will automatically edit the parent intent to add an "Add context" action that is active for the next 1 message:

Note: If a context is active for 2 or more messages, it would be possible to trigger the same follow-up intent multiple times, unless the follow-up intent has a "Remove intent" action. Triggering the same follow-up intent multiple times may result in unwanted behavior in some cases, such as when making a purchase or reservation.

When an intent is added via a follow-up intent, Telerivet associates the new intent with its "parent" intent. By default, follow-up intents are displayed below the parent intent in the intents table. The leftmost column of the intents table shows the ID of the parent intent:

The association between parent and follow-up intents is only used when displaying intents in the Telerivet web app. The actual behavior of the service is defined by the intent's Context and any "Add context" / "Remove context" actions.

Accessing Field Values from Previous Intents

You can refer to field values collected in a previous intent using the state variable like [[state.vars.example]]. When adding a follow-up intent, the help text shows a list of all field variables collected by the parent intent.

Although the help text only shows the state variables for the parent intent when viewing a follow-up intent, it is possible for any intent to use state variables to refer to field values collected by any other intent.

Viewing Intents and Field Types

When viewing a Natural Language service on the Services page, the service is displayed in the same way with a table of intents and a table of custom field types:

Clicking on an intent or custom field type shows the configuration in a modal box. You can click the “Edit” link for an intent or custom field type to go to the Edit Service page with that intent or custom field type open.

Viewing and Exporting Messages

When viewing messages on the Messages page, the intent ID and other data fields are displayed as variables. You can also export the intent ID and other data fields to CSV.

You can use the filters on the All messages, Incoming, and Outgoing tabs to filter messages by any custom variables that are added by the Natural Language Service.

When viewing a natural language service on the Services page, the message icon in the rightmost column makes it easy to quickly filter messages matched by that intent:

Adding Training Phrases from Incoming Messages

When viewing messages for a natural language service (by clicking a link from the Services page), incoming messages have a "Train" link that allows adding a training phrase with the message content:

If the same training phrase is already added to another intent with the same input context, the training phrase will be removed from the other intent.

Using the “Train” link is equivalent to editing the service and adding a training phrase with the message content for the selected intent, and removing that training phrase from any other intents with the same context (if applicable).

Hiding and Renaming Message Variables

On the Messages page, click More > “Manage fields" to view all custom variables used by messages in that project:

You can change the "Field Name" so that the field is displayed with user-friendly text instead of an internal variable name:

If the "Hide values" option is checked, that field will not be displayed when viewing messages, although it will still be shown on the Message Detail page.

Triggering Natural Language Understanding from Another Service

In order to trigger intent detection from another service, first create a Natural Language Understanding service that is manually triggered for a message. Then, in another service that supports custom actions in  the context of a message, add a “Trigger Service for Message” action.

Variables set by the service (such as the intent ID and any data fields) can be accessed after the “Trigger Service for Message” action.

Copying Services

If you make a copy of a Natural Language service, it is initially set in non-initialized mode. If you edit the service and click the “Initialize Agent” button, Telerivet will save the intents and field types from the original service.

Viewing / Reverting to Previous Version

You can view and revert to a previous version of the service on the service's Version History page (Services > More > View version history).

The complete state of all intents and custom field types is stored in the version history for each service. If you use the version history to restore a previous version of a Natural Language service, Telerivet will restore all of the previous intents and custom field types as they existed at the time.