Call Connection in ActionBot
Brief Overview
The Call Connections option in ActionBot gives the ability to call a predefined external API during a conversation.
When calling an API the bot is able to send parameters to the API and to get parameters in the response.
Why use this connector?
Using an external API allows the ActionBot to integrate with multiple systems and provides a variety of options when building a conversation.
The API could be used to send information to an external API (e.g. open an IT ticket), receive information from an external API (e.g. get a ticket number) or both.
How to Use the Call Connection
Check out this short tutorial on using ActionBot to open a ticket on ServiceNow.
Step 1: Create a Connection
This section describes how to add a new connection to the ActionBot editor account. using the connection during a conversation will be done in the next step
- In the Connections section click on "ADD NEW CONNECTION"
- Choose "Add new destination"
3. Define all the needed parameters in the dialog window and click "Create" (This is a configuration step and these parameters should be provided by the API owner)-
-
- Destination name-
- Provide a user-friendly name that will be used to identify the connection later in the process.
- You can choose any name you want.
- Request type-
- Can be GET/POST/DELETE/PUT.
- Should be provided by the API owner.
- Destination URL-
- Has to be a legal API URL.
- Should be provided by the API owner.
- Destination URL may contain dynamic query parameters.
- To create a dynamic query parameter within a destination URL, wrap the string value with curly brackets.
- For example: https://test.api/{production}/
- Destination URL may also contain BBcode variables allowing users to map the dynamic URL parameters to the end-user responses or to use Bbcode supported environment variables such as wm-data, cookies, and jquery
- Authorization type- currently we only support three types of authentication
- No Authentication- doesn't require any info
- Bearer Token- require an authentication token.
- Basic Authentication- requires user+password
- Note that the password for basic authentication can't contain the colon symbol :
- Headers (optional)- some API's require or allow headers
- It is recommended to test the API connection to make sure all details are correct.
- Destination name-
4. New Connection should be added to the list of connections
Step 2: Add action "Call connection" during a conversation
This section will describe how to use a connection, which was defined in the previous step, during a conversation
- Add a new action.
- Choose Action Type "Call Connection" and select call connection destination. The call connection destination is the name of the connection that was defined in the previous step
- When using Call Connections with dynamic query parameters, BBcode variables, or both, users can map end-user responses to the destination URL as dynamic variables.
- Dynamic query parameters and BBcode variables will display beneath the Select Call Connection Destination input when the destination contains a dynamic query parameter or BBcode variable.
- Listed dynamic query parameters or BBcode variables can be mapped to Conversation elements from the dropdown.
3. Define "Data the WalkMe Connection Call sends (optional)
It is possible to send some in-conversation parameters to the API call. In each row, the left side defines which conversation data to send, and the right side will define the name of the parameter the API expects to receive.
In the following example, the API expects to get a parameter named "base", and we will define that the value of "base" will hold the user's answer to a previous question (in this case, "Which currency?")
Clicking on "raw" will allow free editing of the parameters in XML or JSON formats.
4. Define response data mapping (optional)
Some API's return a response, If the response is in XML or JSON formats it is possible to use that response and save it into new variables which could be used later in the conversation
Mapping the response into new Variable-
The user can add as many variables as he wants. for each variable the following needs to be defined:
- Name- choose a name for the new variable
- Don't add special characters in variable names, for example hyphen, dash, colon, ; , (), !*, - {} @
- Type- define the type of the new variable. Currently, we only support primitive types String/Number/Boolean/Array
- Path- define the path in the JSON/XML response which leads to the desired info. To help the user define the path a "path constructor" tool was added. When clicking on it the editor will ping the destination API to receive a sample response, and will allow the user to navigate through the sample response in order to easily define the path. If the API requires a parameter to be sent, the path constructor will ask to provide sample parameters............................
- Default value- this value will be stored in the variable in case the defined path in the response doesn't lead to valid data.
- Error Value- this value will be stored in the variable in case the API call fails.
Step 3: Using the response data variables during the conversation
In case a new variable was created from the response data, it could be used later in the conversation by using "@" in the following cases:
- In a message - display variable to the user as part of a message text
- In a question- display variable to the user as part of the question text
- In a Choice question- display variable as part of the suggestion that will be displayed to the user. For a variable of type array, each field in the array will be displayed as a separate suggestion. If the array contains objects (instead of a single attribute for each item) you can define which attribute will be displayed to the user and which attribute will be stored.
- In a Condition- the condition builder can use the variable as a base for a condition
- In a WM content (e.g. SWT)- when playing a WalkMe content (via action) the variables can be used for data the content requires
Tip Tuesday Video