How to communicate via API

FIRST LINE conversation scripts can help you automatically respond to customer conversations, but in some scenarios you may need to query or notify external APIs. This article briefly introduces how to perform that.

Add Webhook Script

This article will use the free movie database Open Movie Database (OMDb) API as an example to create a scenario where customers search for movies by keyword.

First, we need to go to the system's "Webhook Script" feature to add a new one, using this feature to call external APIs.

Basic Settings

The example settings are as follows:

• Script name: Keyword Movie Search.

• Request URL: This is the external API URL to call when this script is executed; enter https://www.omdbapi.com/ .

• Request method: According to the OMDB documentation, the method is GET

Parameter Settings

Next, in the Params section, according to the OMDB documentation, the API parameters must include the following information:

http://www.omdbapi.com/?apikey=[yourkey]&s=[MovieTitle]

So we enter the following data in this field:

{
  "apikey":  "f4*******4db",
  "s":  "{{ name }}",
  "type":  "movie"
}

Callback Settings

After the API request succeeds, we need to store the required data returned by the API for use in the dialogue script flow. Next, add a Callback setting in the "Webhook Script".

After clicking the Add button, enter the following information in the edit window.

• Action to execute: Because it will be used in the dialogue script function, choose "Update memory variables"

• Parameters: Here we specify which keys the returned JSON data should be stored in; we enter the following code, which means 1. Store the returned totalResults field into the total variable. 2. Store the returned Search into the movies variable, and inform the system to represent it as an array by entering this_is_array.

{
  "total": "{{ totalResults }}",
  "movies": "{{ Search | this_is_array }}"
}

Save the returned data to the current dialogue script

At this point, the API call feature has been configured, and we will continue to add the dialogue script.

Add Dialogue Script

Based on the use case, here we will add a simple dialogue flow to help customers search for related movies by keyword. The flow blocks are set up as follows in order

1. Event: Choose "Customer message matches" and enter * as the match for any message.

2. Action: Choose "Send message" to inform the customer they can search for movies by keyword.

3. Event: Choose "Customer message matches" and enter * as the judgment for any message, and set the "Save customer message as memory variable" field to name, meaning the customer's reply will be stored as the name variable and sent with the API parameters.

4. Action: Choose "Webhook Script" and select the "Keyword Movie Search" script added in the previous step.

5. Action: Choose "Send Message", then in the "Message" field we need to use template syntax to display variables as messages, so enter the following text

The keyword you searched for is {{ name }}

{% for movie in movies %}
    {{ loop.index }}. {{ movie.Title }} ({{ movie. Year }})
    
{% else %}
    No movies have been found.
{% endfor %}


A total of {{ total ?? 0 }} movies.

For more details about template syntax, please refer to the following URL.

👨‍💻Template syntax

Result confirmation

After configuration is complete, when a customer sends a message, the movie search flow will be triggered.

enjoy it!