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
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.
- 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
- Headers (optional)- some API’s require or allow headers
- It is recommended to test the API connection to make sure all details are correct.
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
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
- 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