Search the Help Center
  1. Spotler Engage
  2. Aigent
  3. Actions

Articles in this section

REST API

Inntroduction:

With our REST API integration, one can configure a chatbot to respond based on the result of an API call; via slot filling, either use part of the API call result in a response or make a decision based on it.

We support basic access and bearer token authentication; custom header values, and JSONPath for extracting entities from responses.

To test extraction of your responses with JSONPath, we recommend the online tool, JSONPath Online Evaluator.

 

Configuring a REST API Call:

Navigate to the API Call configuration page via Build -> Actions -> API Calls and click on the "Create New REST API Call" button.

 

When your REST API call is configured, click 'TEST' to run a trial

Description of the fields:

  • REST API Call Name - Enter a descriptive name for this API call, it will be used to identify this call when you use it in the dialog manager.
  • Method - The HTTP method for the request. We currently support GET and POST.
  • REST API Endpoint URL - The address of the request, including the scheme (http or https). If the endpoint requires IP whitelisting, the requests will be sent from the IP: 34.90.135.186.
  • URL Parameters* - The query string in addition to the URL.
  • Headers* - The request headers. By default, we automatically add Content-Type: application/json to all calls.
  • Body* - The body of the REST call, i.e. the content to post to the end point. This is only available for the POST method.
  • Authorization* - Optional authentication mechanism; we currently support basic and bearer token. If these do not meet the end point, see if a custom header entry will work.

     The fields with (*) supports handlebar (double curly braces) for slot filling. These values can be set when the API configuration is used in the dialog.
    • For headers, only the value can be replaced by slot filling.
    • For Authorization, only Bearer token can be replaced by slot filling.

Once the required values are entered, the "Test" becomes available and you can test the API call:

Getting a random Chuck Norris joke by category

Fill in any handlebar values you have for the test, in this case, the category of the joke:

And the response to the call will be shown on the screen:

image2.png

Extracting entities from REST API response:

After successfully configuring an API call, the response from the call can be used as entities by using JSONPath in the API configuration screen. Read more about JSON Path here.

image26.png

Extracting entities from REST response

Description of fields under Extraction Rules:

  • Entity: The name of the entity to store the extracted value
  • Extraction Path (JSONPath): The JSONPath expression to extract the entity from

In the above example, the joke will be set to "After meals, Chuck Norris picks his teeth with a bowie knife.". It will be available as an entity for slot filling in the dialog manager.

JSONPath Online Evaluator can be used to test extraction path expressions. To test the above response, paste the response into the left column, and test your expressions in the input bar:

image20.png

and verify that the extracted value is expected in the right column.

To learn more about JSONPath, click here

Using API nodes:

From the dialog manager, create an API turn by selecting Action->Api from the side bar:

image5.png

Description of screen:

  • Select the API name to use from the drop down
  • The list of handlebars (double curly braces) to fill will be shown below. These corresponds to the slots that need to be filled from the API configuration.
  • Enter the value you want for each of them. Handlebars are also supported here if the values need to be filled from previously filled slots; or simply a string literal like the example above.

image19.png

Example: Token based authentication

Objective

In this example, we will configure a chat bot that will login to the OBI Bots platform using a pre-configured user name and password, and then log in and tell you the name that belongs to that user.

Note: If you have problems following this guide w.r.t. not enough intents to train, just create a user node in another dialog i.e. in the Fallback dialog. This is because in this example not user input is processed and therefore is not a realistic chatbot that the system expects.

image15.png

Login API configuration

First we need to make an API configuration that will login and extract the access token from the response. The access token will allow us to do further API calls as the logged in user.

image13.png

After a test call, we write a JSON path expression to extract the access token:

image21.png

Get current User API configuration:

Next, we will want to get the display name of the user with the given credential in the above step. We will use the extracted access token above as the bearer token.

The API configuration looks like this:

image6.png

Note that we are using the handlebar expression (double curly braces) to indicate we should use an entity's value here via slot filling. The entity is captured in the previously configured login call. If your API uses a long living token, you can just paste it here instead and skip the login call completely.

Next we will extract the display name from the response:

image25.png

The dialog

To illustrate this example, let's create a dialog as the following:

image17.png

Note that we must first use the login call, as this retrieves the access_token and make it available for subsequent call. This turn should be completely hidden from the chat user.

The first API turn is a straightforward one:

image24.png

It is followed by a conditional check to make sure login was successful and we actually was able to retrieve a token. This is not strictly necessary but some form of error handling is always recommended.

image12.png

Here we simply check that the access_token entity we want to extract from the first API call actually exists. In the event of failure to login, the bot will branch the conversation off to the "No Conditional Match" side of the conversation.

Next, we will make the second API call. We need to use the previously extracted access_token in this call, and so we configure it as so:

image16.png

And finally, we have the bot respond by telling you your name:

image3.png

Testing

image1.png

Als je geen gebruikersnaam hebt ingesteld, vertelt de bot natuurlijk gewoon jouw e-mailadres.

Example: The Cocktail DB API

Objective

Here we will create a chat bot that accepts the name of a drink entered by user and searches for information about it in a free cocktail database. The provided information should include the ingredients and the preparation instructions of the drink.

 

API configuration

Our API Call must be set up to take the captured user's answer as a search_string parameter (see Configuring an API Call for more detailed information):

image23.png

 

Then we extract the required information from the response by means of JSON path expressions (more on this here -Extracting entities from API response):

image22.png

 

The dialog

Let's build a simple dialog with a User Turn (1) that has cocktail.info intent and cocktail.name entity to capture the input:

image4.png

In the following Action Turn (2), we pass our entity value as the API request parameter:

image11.png

And the final step is to reply with the collected information in Bot Turn (3):

image8.png

Testing

Make sure the bot has been trained and check the result:

image27.png