Introduction
The API Call Flow Node provides a mechanism for accessing data external to the current flow or to the Zai Conversations System. As the name suggests, the API Call Node allows the Administrator creating an interaction flow to make an HTTP request to a third-party resource in order to either fetch or store data that is used in the flow. This data can be used in order to make decisions regarding the path that the flow takes as well as to provide a more efficient and personalized experience for the caller.
The most common usage of an API Call in a call flow is to perform a “Data Dip” and fetch information from a third party resource. This resource can take the form of a database, CRM system, ticketing system, or any other line of business application. The API Call Node provides a number of ways an Administrator can configure an HTTP request in order to fetch data using path variables, query parameters, or body parameters. The Administrator can also map output to discrete variables which can be referenced later in the flow. The API Call Node provides a powerful mechanism for parsing complex JSON structures and assigning values to variables in a simple and effective manner.
The other usage of the API Call Node is to push data collected in the flow to a third-party resource. This data can take the form of captured inputs from the caller’s dial pad or data describing the call’s path through a particular flow. The API Call Node provides the Administrator with an easy to use mechanism for uploading custom data to external resources.
The API Call Node is designed with simplicity in mind and can be easily configured using the 3-step wizard provided in the Interaction Flow Designer. These steps are described in more detail in the following sections.
The API Call Node is available only for Contact Centre Flow types.
Configuring the API Call
The API Call Node is found first in the list of available nodes.
The API Call Node can be placed after any other node with the exception of an End Node or a Call Forward Node.
Name
The first screen in the configuration wizard requires the Administrator to give a name to the API Call. This name should describe the integration type, providing information regarding which operation it is performing.
The Name field is required.
Request
The Request step of the wizard allows the Administrator to define what type of request they would like to perform.
The first field to configure is the HTTP method that will be used.
The options available are GET, POST, and PUT. The method field is required for the configuration of the API Call.
The next step is the URL:
This must be a fully qualified URL, for example:
http://api.zailab.com/some-resource
The API Call node supports http as well as SSL/TLS (https). In order to ensure the security of data, https is strongly recommended.
The URL can accept path variables as well as query parameters:
http://api.zailab.com/some-resource/${resourceId}?queryParam=${queryId}
Where ${resourceId} refers to a variable that has already been set called resourceId and queryId refers to a variable that has already been set called queryId.
Any variable referenced must be enclosed within ${}. The ZaiLab flow processor will substitute the variable value for this placeholder if it can find the variable.
The URL is a required field.
Following the URL, the request headers can optionally be set:
The headers can be any number of key-value pairs that are required. Common header values would be Content-Type headers as well as Authentication/Authorization headers.
The Administrator can add each key-value pair and click the ‘+’ icon on the right-hand side to add the header to the request. The ‘+’ icon will then change to a delete icon to remove the header.
The final element of the request is the body:
The Request Body is a free-form text field. The Administrator can place any text in here they wish to be sent with the request. The example above shows a simple JSON payload. Variables can be referenced within the Request Body by enclosing them in ${}.
Response
The response step of the wizard allows the Administrator to bind values from the output to variables that will be saved in the flow.
The ZaiLab flow processor allows for the parsing of JSON data by using a pathing system that references each JSON object separated by a ‘.’. The root of this path is always denoted by the keyword result. To explain this by way of an example, consider the following JSON payload:
{
“name”: “Bar”,
“foo”: [
{
“name”: “FooName1”
},
{
“name”: “FooName2”
}
]
}
The above JSON response contains an object with a “name” property as well as a list of objects, each of which has a “name” property too.
In the variables configured above, VARIABLE_ONE references the result object’s property named “name” and would therefore be set to the value “Bar”.
VARIABLE_TWO references the result object’s property “foo” and then references the first item in the list (entry 0) and references that element’s property called “name”. This would be set to “FooName1”
Referencing the result object directly will set the entire response to be set to the specified variable.