Global library

The global library has three features that help build your Conversations:

1. Actions: The complete specification on how to use a particular API endpoint including the url, methods, parameters and authentication information. Basically how to interact with other systems.

2. Conversation snippets: A reusable (within a chatbot) piece of conversations often used to capture the variable value. The reusable parts of your chatbot's conversational text, either statements or questions.

3. Variables: The set including all API outputs(computed variables) and all collected variables. We can refer to variables in the bot response during the setup time and the bot will automatically replace the reference with the value at runtime. Variables are how your chatbot stores information.

Actions

In simple words, Actions are the wrapper that allows the chatbot to interact with API's in order to retrieve data from an external source or to perform operations in a different system.

An example of retreiving data from an external source, we can imagine a Skill configured to help the user get the weather for a certain city. In the Skill flow the city of interest for the user would be collected by the chatbot and then eventually used to query a weather API, through an Action, and get the temperature value to display to the user.

An example of performing an operation could instead be a meeting booking bot. The Skill is configured to collect a date and time that fits the user, along with their email. After all the information has been collected, the data is sent, through an Action, to the calendar APIs to create a new meeting event.

Actions can either be configured manually by providing the below mandatory parameters or the template can be imported by using the 'Import from template' option.

To use this import template feature, create a new action and click on the ‘Import from template’ option in the top right and select the template to create the action. Provide the API configuration and input parameter details to create the action from the template. Click on ‘Save’ to complete the action creation.

Import template - API integration

Sendgrid

Sendgrid is a cloud-based SMTP provider that allows you to send an email without having to maintain email servers. You need your own Sendgrid account and API to use this integration. This is useful to use when you need to send reminders or alert someone via email from the chatbot.

Gavagai Tonality API

It supports a number of different languages. For each of these we actively track current online language use to enable a number of features of the API: multi-dimensional sentiment extraction for a set of predefined attitudes for each language (see the discussion for the /tonality call); up-to-date and timely information about words and their relationships through the /keywords and /lexicon calls.

Languages are specified according to ISO 639-1. You can find the currently available languages by calling the /languages resource in Gavagai Api.

A complete action is defined by three types of objects: the API definition, the input parameters and the output variables.

To set up an action you will need to have access to the endpoint that you want to connect to and its documentation, it's the only step in the process that requires some technical Skills.

API Definition

In this section of the action configuration you will need to specify all the general information of the endpoint including the URL where the resource is located, the HTTP method that needs to be used (POST, GET, etc...) and the details of the authentication, if necessary.

Input parameters with the type ‘path’ can be used in the endpoint URL to assign the value dynamically during the chat session. It can be referenced in the endpoint url with the open and close double curly brackets. A warning message will be displayed when the input parameter with the type ‘path’is not referenced in the endpoint url. Likewise a warning message will be displayed when the parameter which hasn't been created is referenced in the URL. E.g. Endpoint URL -https://api/v2/{{XXX}}/test

Input parameters

The input parameters are the placeholders for the data that will be sent to the endpoint. Each input parameter contains the information about how to pass that piece of data when performing the request.

Parameters to create a new input parameter.

1. Input parameter key: name of the API parameter that will be passed when calling the endpoint.

2. Input parameter name: Provide a user-friendly name for the API parameter. Use a name that represents the information the endpoint needs. E.g. if the API requires an input parameter with the name "q", that stands for query, use "query" as a user-friendly name.

3. Description: Brief description about the parameter

4. Request parameter: Type of the parameter. It can be path, header, query and body.

5. Is it a constant toggle button : Turn it on if the parameter is a constant. Once it’s turned on the constant value field will appear on the screen else it remains as an empty input that will be mapped and filled dynamically with a variable collected by a snippet.

6. Constant Value: Provide a static value to the parameter (e.g. an API key).

Advanced configuration

Now the complex data structure can be passed as a request body schema by using this feature. Create the required input parameters and open the ‘Advanced Configuration’ window. Complex data structure can be configured now by using the input parameters.

Input parameters can be raw values or processed values:

Raw values

Use raw values when you want to use an input parameter as a standalone value. Raw values can not be combined with text or other input parameters. It'll be shown as $(use-:-parameter).

Processed values

Use processed values when you want the input parameter to be combined with other input parameters or you want to include it inside text. It'll be shown as $(ref-:-parameter). To combine an input parameter with text or other input parameters, simply reference it inside a String. E.g.: "This is a text with $(ref-:-parameter1) and $(ref-:-parameter2)"

Right click on the editor to add input parameters(raw/processed) and configure how the data will be sent to the API endpoint.

This feature is available only for 'Body' and not for 'Header and Params'.

Output variables

The output variables are the relevant information parsed out of the API response. For each of them you will need to specify the ‘variable name’ and JSON path as ‘output path’ to extract them from the response object. Output variables are the computed variables and it can be used when building snippets for a bot.

For an array, add the index in square brackets (e.g. results/[2]/property). Note that the first item of the array will be 0, since arrays have a zero-based index.

For an object, reference properties like the following: results/['id'='1']/result, where id is the name of the property and 1 its value. In the variable name field, assign a variable name to the output path.

If an object doesn’t exist in the action result or an array parameter is out of a list then the variable value of the output parameter will be set to ‘N/A’. The condition type ‘Is available’ can be used to check if the value of an output variable is available (hence different from ‘N/A’) in the skill flow.

Edit an action

Action objects can be edited at any time as mentioned below.

To update ‘Configure API call items, Click on the pencil icon beside the parameter and then the element will be in editable state. Update the element and click on the tick mark or press enter key.

To update input and advanced configuration - Click on the parameter, change/add the parameter details and click on the ‘Update’ button.

Output path can be edited by using the ‘edit’ option which is present after that particular output parameter.

Delete an action

Existing action can be deleted by using the ‘Delete’ option. Click on the ellipsis of the Action which you wanted to remove and click on Delete.

Conversation snippets

In simple words, a conversation snippet is what will make a chat between the user and the bot possible. Alongside with Actions, they are the building blocks of a Skill. There are two types of conversation snippets: simple snippets and collecting variable snippets. Basically statements or questions that the chatbot can say or ask.

Simple conversation snippet

This is basically what the chatbot can say. A piece of text that the bot will output at some point during the chat. For instance, a bot that has the Skill "Open an account" might say "Your account has just been created. Welcome!". The chatbot admin should create a "Welcome Message" conversation snippet with the previous text and add it in the Skill, right after the Open an account action. The bot will use that snippet once the account has been successfully created.

Collecting variable conversation snippet

This is basically what the chatbot can ask, to collect information. A three-step interaction between the bot and the user in order to get a piece of information, which will be saved as the value of a variable. The three steps needed are:

Ask: The chatbot admin will provide examples of how to ask for that piece of information.

Inform: Examples of how the user might give that information. For example, If the snippet is created to collect the name of the userthen the examples can be, “My name is \<name+>” , “I’m \<name+>”, “Friends call me \<name+>”, “People call me \<name+>”, “I call myself \<name+>” and “\<name+>”. Note you will need to create variables to store that information. Please see the variables section: 3.1.3 Variables

Acknowledge: Messages can be displayed to the user after receiving the expected input. Also the bot will not move forward until receiving the expectedinput from the user. This can be for example, "Hi \<name+>, nice to meet you!". This is not necessary.

Link,variable reference and buttons in conversation snippet

Snippets can contain buttons, variables reference and html links in the messages.

Links -To provide the link to the appropriate webpage in the bot’s question/response.

Variable reference - To display the collected variable value in the bot response.

Buttons - To perform a particular action based on the user selection during the conversation. There are three types of buttons available for the snippet. See types of buttons for more information.

Multiple chat bubbles

Any number of responses can be added in the conversation snippet by using the ‘Add bubble’ option. During the conversation, all the messages will be presented to the user. Note that this option will be visible only after adding the first message.

Edit the conversation snippet

Created conversation snippets can be edited at any time. Open the conversation snippet and click on the pencil icon in the chat bubble which is visible on hover to edit the message.

Delete the conversation snippet

Conversation snippets can be deleted using the ‘Delete’ option if they are no longer needed. Click on the ellipsis of the conversation snippet which you wanted to remove and click on delete option.

Variables

A variable represents a piece of information acquired from the user input or as a result of an API action.

Computed variables:

Computed variables have their value set by the response of the API action.

The variables which are created while adding an action to a skill block to map the action’s output parameters are also considered as computed variables with an option to edit and delete. Note that the system will not allow you to delete the variable if it's being used somewhere in the bot.

Collected variables:

Collected variables are those whose value comes from the user input. An entity type defines the type of information you want to extract from the user's input. Conversation snippets are used to collect the variable value from the user.

Entity type

An entity type defines the type of information you want to extract from the user's input. For instance, animals could be an entity type. For each entity type you should provide examples, which are called entities. An entity is a real-world object, such as persons, locations, organisations, products, etc., that can be denoted with a proper name. For our Animal entity type, the entities (examples) could be dog, cat, cow, donkey, goat, mouse, etc.

When adding an example to the existing entity or new entity, new similar examples will be listed as suggestions. The user can either add ‘All’ the suggestion or can select the specific items to add as an entity example.

System defined entity types

By default, the chatbot has few commonly used entity types which can be used while creating a variable.

Name - Name of the person and more examples can be added by entering manually or from suggestions.

Organization - Name of the organizations and more examples can be added by entering manually or from suggestions.

Number - It can be used for the variables which are collecting the number valuesand this entity type is not editable. This is compatible with string, integers, and floats, but it will be stored as a float.

Date - It can be used for the variables which are collecting the date and this entity type is not editable.

Email - It can be used for the variables which are collecting the email addresses and this entity type is not editable.

Phone_number - It can be used for the variables which are collecting the phone number and this entity type is not editable.

Free text - This entity type will capture the user’s answer and store the variable value based on the expected user input format defined by the user in the conversation snippet . If the user input is not matching with any of the defined examples then the entire input will be considered as a variable value. Free text entity type is not editable.

Yes/No-This entity is used to capture the boolean value and this entity type is not editable.

Entity type customization

Apart from the system defined entity types, users are allowed to create their own entity types based on their requirements. To create a new entity,

Click on the ‘Create new variable’ button and click on the ‘Create a new one’ link in the new variable pop-up. Provide the below parameters and click on the ‘Save’ button to create a new entity type which can be used to create variables.

Name - Provide a name for the entity Description - Brief description about the entity.

Type of information - Select the type of data which can be stored as a variable value when using this entity. It can be date, number and text.

Examples : Provide the examples for that entity type. Examples can be added manually or can be added form the list of suggestions provided by the system. There should be one example to get the list of suggestions.

Select the checkbox of suggestions which you wanted to add and click on the ‘Add suggestions’ button.

Create, edit and delete a variable

Click on ‘Create a new variable’ button to create a new variable. Click on ‘Save’ after providing the variable name and entity type. Created variables will now be presented in the list of collected variables.

To edit the variable, Click on the edit option from the ellipsis of the variable which you want to edit. Now the variable name and the entity type can be edited and saved by using the update button.

To delete a variable, Click on the delete option from the ellipsis of the variable which you want to delete. Confirmation pop-up will be prompted with the message ‘Are You Sure? Deleting the variable \<variable_name> may break a chatbot Skill. Are you sure you want to delete it?’ to reassure the deletion of a variable. Click on ‘Delete’ to remove the variable. Variables associated with the snippet /Skill can’t be deleted until the association is removed.