Integration with third-party APIs

This article presents an example of creating a bot working with inner API Wilfire (it sends and receives information)

You can create bots that interact with other resources with API. For example, bots can comply with requests with the ability to check if creating an appointment for a certain date is possible, or find a product in an online-shop.

How to handle third-party API on the example of DaData

Let’s take API tips from https://dadata.ru/api/suggest/address as an example

Carefully read documentation of third-party APIs

Open up your project in Salebot and open advanced settings in the settings of a block; there you need to change the request type to POST-json.

In the field “URL request” enter the following URL: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address

In the field “Request header” type in the header in the JSON format:

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

In the “JSON parameters” put in the request itself - { "query": "#{CurrencyType}" }

To get the results you’ll also need to fill out the “Stored values” tab.

An example of the request is below:

How to save values from variables

Not everyone gets it instantly, until you try to do it yourself.

To start type in #{custom_answer} in the answer field. (The variable #{custom_answer} holds the answer gotten from the server that was mentioned in the field “URL for an answer from the server”)

Launch the block with the request to send the request and to get an answer to it. You need to analyze the reply and set up access to the variables in it. For this, you need to work with the “Stored values” tab.

Let’s look into an example to understand the process better.

As a result of our request #{custom_answer} an answer of the format came in:

{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}

Now let’s write in the field “Stored values” our VALUE->VARIABLE

suggestions|0|value->CurrencyType; suggestions|0|data|code->CurrencyDigCode; suggestions|0|data|strcode->CurrencyStrCode; suggestions|0|data|country->CurrencyCountry

suggestions - the key of the array [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]

suggestions|0 - the key of the first element in the array {"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}

suggestions|0|value - the key to the value “British pound”

The longest key in this JSON:

suggestions|0|data|strcode - the key to the value “GBP”

Keys are separated with the vertical line (|). If there is an array in JSON, then the access to its element is numbered, beginning with the number 0 and it’s also written down with the vertical line.

It’s necessary to repeat the whole nesting. For comfort you can visualize JSON in an app JSON-viewer.

Nesting levels are separated by vertical lines. So you need to list all keys separated by the line to get to the value.

If there is an array in JSON then instead of the key you need to mention the number of the element starting with 0.

Separate phrases of obtaining variables by the semicolon symbol (;). The phrases consist of the link to the data in the answer and the name of the variable to save it in, which are separated by symbols -> (the dash + angle bracket).

The search query is, in a way, a path in JSON to the needed value.

Developing API for bots

To develop an API, you’ll need a hosting on which it will be based on. If you don’t have one or you aren't an ace in programming, then you can reach out to us and we will develop the API for your bot and base it on ours. The hosting itself is free, you’ll only be paying for development.

But for now a little bit of theory.

The bot supports the GET and POST requests, these are the main types that are used in most public APIs.

GET is a request that happens with the click on the link or when opening the link in the browser. Parameters in such a request are transferred to URL-requests.

The syntax of transferred parameters: after the url there’s a question mark (?) then every parameter is separated with the ampersand (&). A parameter consists of the name and its value after the equal sign (=). An example of a URL with a parameter:

Here you can see that one parameter by the name of “search_query” is being shared and that its value is “queen live aid”. The ‘+’ here is the space between the words; when working with the editing software you can just leave the spaces – the bot will change it itself.

POST is a type of request that gets sent when filling out a form on a website the most often. The request transfers the parameters in the body; of course, they can be shared the same way as GET but it’s rarely done this way. The parameter in the body can be in the JSON format or as a key-value. As key-values the parameters share forms, the JSON format is the one that is used most often for API.

Request header. Every request can have an added header/title. The format of the shared data and access keys are written in it most often. Usually we leave this tab empty, but it is needed to put in the API Token or the request type “Content-type”: “application/json” on rare occasions.

JSON - (JavaScript Object Notation) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays. To work with the API in bots you have to know this format, everything is based on it.

Before continuing, read the following articles:

https://www.json.org/json-en.html https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json

And also try to create your own JSON file on this site:

https://jsoneditoronline.org

Practice

Blocks and conditions can comply with requests. The condition requests are created to understand on the site if the dialogue can follow a certain path or not. The request in this case happens every time the path’s condition is checked. The blocks’ requests on the contrary are only run when the move into the block happens.

Before creating a request you need to choose its type:

POST-data and POST-json are differentiated by the method of transferring parameters as mentioned above (JSON format or as a key-value). If you choose JSON then the parameters can be transferred in the request only. An additional field opens for the post: JSON POST-parameters. Important! The parameters must be written in the JSON format only, the bot only works this way.

The reply from the server can be parsed and saved in the variables.

You can make out the reply only if it is in the JSON format.

The saved variables are written down in the last not filled out submission; if the submission is transferred through a red block, the variables are annulled. So if you need to save the data, you need to transfer variables through the yellow block.

By the way, you can see what the bot has written down in the variables in the section Leads:

Data transfer not as a line

By default variable value comes in the #{} format but then it comes as a line. To make the variable be transferred as a number you need to turn off checking the format of post-json parameters.

Then you can just mention the name of tha variable, like {"key": #{variable_name}}, variable_name is the variable, so without using brackets.

After setting up parameters it is recommended to turn checking back on.