Intent Programs

In this page you will find more information about Intent Programs. It details some concepts show in the Quick Start Intent section.

If you’re looking for information about FAQ Programs, check the Quick Start FAQ section.

Table of Contents

Shapes

Shapes are the nodes in the Designer Flow, in Programs of type Intent. You can drag and drop them to the Designer area, and create your flow by creating connections between Shapes. This is how the conversational flow is designed/built. In the following chapters there’s a description of the different Shapes.

Eval

Eval Shape is used when you want to check a condition, and you need to define different conversational paths based on the result of that condition. The result is either True or False. Example conditions: if (varValue=A) then go to node Answer1, else go to node Answer2.

Answer

Answers define what the Virtual assistant responds to a human user (to its intent). Answers can be defined for a single channel and/or for multiple channels at once. For text-based channels, it can be composed of "components" (such as text, images, videos, cards, menus) and/or actions to an external system (for example IVR or other channels). For more information, view the Answers page.

Program

Using the Program Shape in a conversational flow will "call" a different Program. In practice, this means the conversational flow will be "transfered" to a different Program, but the current one is still under the session's context, and can still be "called".

Link

The Link Shape will transfer the conversation to a different node in the same Program (it will "jump" to a node). This allows to simplify the tree of complex Intent Programs.

Operator

Using the Operator Shape will transfer the conversation to a human operator, so the user can resume the conversation and solve its inquiry.

SMS

The SMS shape allows you to incorporate the sending of SMSs into the flow. It can be used to send messages to one or more phone numbers.

APIs and Storage Bucket Shapes

The APIs and Storage Buckets defined on your account will be visible as Shapes in the Designer Flow (Intent Programs), below the previous described shapes.

APIs

You use an API shape during the conversational flow when you have all the information required to call the API. You will need to define all the input parameters, and define variable(s) with the information that the API returns.

Storage Bucket

The Storage Bucket shape is used when you need to save information or read previously saved information. This saved information will be stored in the database and will be available for some time after the session is closed (the conversation ends).

General configurations

General configurations helps to specify the type o connection you want to establish between your shapes in the Designer Flow, in Programs of type Intent. Those connection configurations are common to the Shapes and the Connections. Although, some shapes like Link, Operator and Chatwood present their own configurations, specifically adapted to the needs of each particular feature.

Set Values

This section allows to set a value (fixed or variable) to variables.

Script execution

This section contains javascript expressions, that allow to control the flow.

Using the keyboard, press simultaneously the Ctrl+Space keys (or Shift+Ctrl+Space) and the variable selection screen should show up. Select the variable you want to work with.

Your script execution element should look like this:

You can press Cancel or Save this script, and go back to the Designer Flow screen.

Available API’s

It’s possible to use third-party apis in BOTSchool scripts (under Script execution and Conditions fields).

Jose

jose provides APIs to encrypt and decrypt messages and to sign and verify messages.

For detailed information you can consult the official documentation

jose API methods and objects are available under JWT scope.

CryptoJs

CryptoJs provides APIs of standard and secure cryptographic algorithms.

For detailed information you can consult the official documentation

Connection

Connection helps to specify the type o connection you want to establish between your shapes in the Designer Flow, in Programs of type Intent. Connections can be made in several different ways:

1. selecting two shapes and clicking on the "connect" button
2. through one of the shape's points, dropping the connection on the destination shape
3. through one of the shape's points, dropping the connection out of a shape (inside the designer flow canvas)
4. changing the connection from one shape to another - it is now possible to change the source or destination of each connection

General connection configurations

Those connection configurations are common to the Intent connection configurations and the Evaluation connection configurations.

Tags

Tags are used to mark the interaction flow, in order to know the path that was taken by the student to answer the question posed by the user. All tags that the stream went through in an interaction will be shown in the student dialogs table.

Intent connection configurations

Intent connection configurations is used on the creation of the connections when shape of origin is Answer.

Connection type

Here you can specify the connection type you need to trigger. For example, you can identify it as an intent connection type, file upload, mark as fallback connection, or as a jump to faq program.

Eligibility scope

Eligibility scope can only be used on the creation of connections, when shape of origin is Start.

It presents two types of eligibility scope:

1. default
2. always on - it enables a possibility of defining a particular shape that can be trigger at any point of the dialog flow.

Intent

Helps you to identify the intent and related training phrases, that will be used to trigger the flow of the dialog. The lists shows all the intends except the one that is already used in the shape of origin.

Evaluation connection configurations

Evaluation connection configurations is used on the creation of the connections when shape of origin is API, Storage Bucket or Eval.

Condition

Condition seeks to evaluate, and its’ content must respect javaScript syntax. To continue the flow the output must be true. The condition accepts variables defined for the program or fixed text.

Relational operators allowed:

1. greater than
2. greater than or equal to
3. less than
4. less than or equal to
5. !=
6. ==
7. equal (compares content between the 2 parts of the condition)
8. ===
9. not equal
10. equal (for the 2 parts of the condition compares variable type and content)
11. Logical operators allowed: || or && and ! not
12. Regex

For more information, consult JavaScript documentation.

Entities and Variables

Entities and Variables section describes the use of Entities and Variables to enhance programs.

Entities and Variables are used to extract useful information from the user input.

When people speak with Virtual Assistants, they express their intent as the natural way they communicate with other humans. The phrases uttered can be mapped internally in the following ways:

1. as fixed, in plain text - example: how is the weather in Lisbon - in this case the student only knows how to answer about the weather in Lisbon,
2. by using Variables - the variable is internally associated to an Entity, that can be used to convert the user question into a dynamic phrase - example: how is the weather in «city»

where «city» is a variable and it will be replaced by any city the user says.

Variables in the context of speech examples configuration (training phrases) that are provided by the BOTSchool user, are Variables of the Entity type.

The platform allows users to select System Entities (such as countries, cities, numbers) and for such Entities, the user doesn’t need to define them. They are available to use directly on the program. However, if the system can’t recognize certain words, users can access the entites area and add synonyms to different system entities, such as location, address, registration and person.

The platform also allows users to create Entities that are specific for the context of the program where they will be used, for example Weather.

The Weather Entity is used to understand what the user is saying in different sentences, but that hold the same meaning, based on Entities that are synonyms.

Example of Weather synonyms: temperature, meteo, weather forecast, climate, atmosphere.

Having a variable (var) whose type is Entity Weather, the following sentence can be configured:

1. how is the «var»

and internally, the «var» will be mapped into «weather»‘s synonyms. The knowledge provided to the student will allow it to answer sentences such as:

1. how is the weather
2. how is the temperature
3. how is the meteo
4. how is the weather forecast
5. how is the climate
6. how is the atmosphere

without the user having to configure all of them as training phrases.

The user can also use regex - a regular expression - which is a sequence of characters that specifies a search pattern in text.

Synonyms

To simplify the teaching process, the School allows the definition of training phases based on synonyms, which help the user not have to define similar questions for the same answer.

Synonym is a word or set of words defined in an Entity, that means exactly or nearly the same as another word, for the context where it was configured.

They are equivalent or analogue words.

In the scope of School, the use of synonyms facilitates the task of configuring the training phrases.

Users only need to configure the training phrase using the “main name”.

The platform will automatically apply the same training phrase to all synonyms defined.

Entities and Variables Example

Lets apply these Entity / Variable and Synonyms definitions into a real example.

1. A training phrase into an intent can be divided in the subject and verbal components as well as corresponding Entities.
2. It is easier to understand this with an example: Tell me the weather for tomorrow.
3. The sentence is composed by the verbal component Tell, the noun me, and Entities: weather and tomorrow.
4. The Entity weather is the what and tomorrow is the when.
5. When composing an answer, a weather answering bot should reply based on the Entities provided, in this case, weather tomorrow (and not weather today for example).
6. But before delving into the when, lets start by creating a simple program associated with the DOC_BOT with an intent named weather.
• Use the following training phrases:

---

1. Tell me the weather
2. How is the weather
3. What’s the temperature

---

Afterwards and just to have a program with two clear intents, add a location intent with two training phrases:

---

1. in Lisbon
2. in London

---

Your training phrases should look like this:



Draw a connection between the first weather intent and a generic answer: In what city?

After that, draw a connection between the location intent and a generic answer: Sunny all day

• Save the diagram and test it. It should all look like this:

  

• The program is currently very basic and uses no real Entities. The values are static. Let’s change that.

• Let’s create our first Entity for atmospheric conditions.

• Go to the Entities tab and add a new Entity by pressing the + icon.

  

• In the popup screen name the Entity atmosphere, use atmosphere as value and add the following synonyms:

---

1. rain
2. sunny
3. snow
4. haze

---

To insert a new synonym, write it and press Enter.

• The screen should look like this before saving:

  

• After saving the Entity screen should look like this:

  

• Go back to the Intent edition tab and edit the training phrases.

  

• Click the intent variables add.

• In it create a new Variable named atmosphere of a Custom nature and associate it to the atmosphere Entity like shown:

  

• Save this variable and go back to the training phrase screen.

• Select the intent, and change the third training phrase to:

---

1. “Is it "

---

• Keep the cursor on the training phrase. Now we will insert the variable. Using the keyboard, press simultaneously the keys Ctrl+Space (or Shift+Ctrl+Space) and the variable selection screen should show up.

  

• Select the variable atmosphere from the list. Press Enter to confirm the use of this variable and the screen should appear like this:

  

• The background of the variable name and type (its a custom type in this case) is highlighted.

• Save the Intent go back to the Designer Flow and Save, and Train.

• You can now test that Intent using all the synonyms asking the weather atmospheric conditions. Remember, the user utterances must be similar to the training phrases defined in the Intent.

  

Variables

• While the atmosphere Entity was used as a variable, the Entity itself is a holder of a few synonyms.
• This tutorial will work with Variables that may be used for further processing.
• First, going back to the second question our student asks after identifying the weather intent:

---

1. Where?

---

• The Program uses two training phrases which are cities, but realistically, it should be able to answer the question for any city.
• For the purpose of understanding a sentence with the city, it doesn’t matter which city it is. But for the generation of the answer, the information of the city is vital for a correct answer.

Session Variables

When designing the flow, it is possible to access a set of Variables in the shapes and connections. These Variables values, defined in each session, are fulfilled during a conversation act with a given user, and can be divided into a few groups.

The Generic Variables present information such as the student’s language, or name. The different variables and respective values of this group are below.

Generic Variable	Value
generic.language	the language the student knows
generic.studentName	the name of the student
generic.languageDetected	the language detected in the last interaction
generic.sentiment	the sentiment of the last interaction, which can be Positive, Neutral or Negative

Focusing on sessions, Session Variables are composed by relevant information about the current session, including the channel where the conversation between the student and the user is being conducted, and the user’s last input or the student’s last response. All of these variables as well as their associated values are displayed below.

Session Variable	Value
session.sessionId	an identifier of the session
session.channel	the channel where the conversation is being conducted during the session, which can be web, whatsapp, etc.
session.lastUserSays	the user’s last input in the session
session.lastBotResponse	the student’s last response in the session
session.isTest	whether the last input was received through a test execution in the school
session.numberOperatorInteractions	the number of interactions between the user and an operator, when there is an operator shape in the flow
session.username	the user’s login username
session.lastCreatedBucketInstance	the identifier of the last insertion of a given bucket
session.sessionSentiment	the predominant sentiment throughout the session, which values can be -1, 0 or 1
session.trendingSentiment	the sentiment’s direction throughout the session, which can be Upwards or Downwards

As for the Intent Variables, these allow to access information related to the intent identified in a given interaction, such as its confidence value and the given name when created. The two variables and respective values are below.

Intent Variable	Value
intent.friendlyName	the name of the identified intent
intent.confidence	the confidence value of the identified intent

There is also a set of variables associated with file uploading, the File Upload Variables, composed by relevant information such as the name of the uploaded file, or its content. These variables, along with the associated values, are displayed below.

File Upload Variable	Value
fileUpload.name	the name of the last uploaded file
fileUpload.content	the content of the last uploaded file
fileUpload.mimeType	the mime type of the last uploaded file, which specifies the file extension
fileUpload.size	the size of the last uploaded file

When the interaction between a user and a student is conducted through a whatsapp channel, the Whatsapp Variable allows to access the user’s phone number.

Whatsapp Variable	Value
whatsapp.originNumber	the phone number from where the user interaction began

Finally, Auth JWT Token variables allow to display different aspects related to the JWT token, including the token itself, its name or type. Below are some examples of these variables and respective values. The remaining and more specific JWT Token variables can be accessed through `auth.jwt.<param>`.

Auth JWT Token Variable	Value
auth.jwt.token	the jwt token
auth.jwt.name	the jwt token name
auth.jwt.typ	the jwt token type

Files

BOTSchool now supports file upload and download functionalities in intent-type programs, currently only available for whatsapp channel. As such, it is possible to include these new features in the flow. Let’s see how to configure each of them.

Upload

For the file upload functionality, it’s necessary to create a “File Upload” connection, which will point to the API that will receive the file.

In this connection, the variables related to the file being uploaded (like fileUpload.content) can be assigned in the set values field, to be stored in variables of the flow. For that, it will be necessary to create, in the variables section, variables of type file, and then make the assignment in the set values ​​field of the connection.

After the connection is configured, an API shape will have to be placed in the flow, to receive the file. In this API (which must be previously created in the fulfillments area), it is necessary to send two fields as input values:

1. filename - which can be the variable fileUpload.name;
2. content - which can be the variable that will contain the base64 of the file that will be sent, and that was previously saved in a local variable of the program (in this case it is called "fileContent").

Download

For the file download functionality, it is also necessary to previously create and configure an API in the fulfillments area, which will return the files that will be presented to the user. In this feature, the flow will only need an API and a document type response.

In the API configuration, in the fulfillment answer definitions section, it will be necessary to add variables of type file, to save the respective files.

Next, you need to go back to the flow and open the API shape, where these variables will be available for assignment in the set values ​​field. Therefore, it is necessary to save that file in a variable of type file in the program, to be available in the entire flow.

Then, all that is left is the configuration of the document type response, using the previous variable as a URL and choosing a name for the file (which must contain the file extension, as in the following example).

Updated on 03 Nov 2022