External APIs

Not only humans but also programs might be on the other end of a conversation. But what if we also get substituted by a program?

An API (or application program interface) specifies how different programs should interact. Thanks to APIs Pipebots are also able to communicate with external programs and IoT.

APIs interact using JSON format. Basically, JSON presents answers as {variable: "value"}, where braces define the structure of an answer.

🐫 Install JSONView plugin for Chrome or use JSON Online Editor to see the structure of an answer.

Let’s figure out how it works by requesting bitcoin price:

View without the plugin

{"high": "17234.99", "last": "16789.02", "timestamp": "1515294364", "bid": "16789.02", "vwap": "16658.97", "volume": "8288.43967678", "low": "16220.00", "ask": "16800.10", "open": "17142.43"}

View by JSONView plugin

Simple query

A simple API query is used to process those answers, that don’t require authorization or setting any parameters.

Let’s request current bitcoin price. Just add the following to the node:

%BTCPrice=/get ask https://www.bitstamp.net/api/v2/ticker/btcusd/,

where /get — query type;

ask — variable name, contained in the answer, whose value is requested;

URL — API web address without parameters;

%BTCPrice — variable, that contains the required value.

Full query

If authorization and parameters setup are mandatory a full API query is used. For example let’s check how natural language processing works:

Click icon to copy this map or open it in

These queries are indicated as $SYS.GET, $SYS.POST, $SYS.DELETE and $SYS.PUT in the nodes.

QUESTION node includes all necessary query parameters. In our example: v — protocol version; query — text from the human’s message; sessionid — conversation ID (or user ID (uid) to identify the human); lang — language in use.

All requested variables are collected from JSON into ANSWER node.

%answ=result.fulfilment.speech

One can also receive the full raw answer by presenting %raw variable (refer to the example).

JSON allows to pick up value of any target element by specifying the search field. Let`s collect the specific currency rate from the query https://bank.gov.ua/NBUStatService/v1/statdirectory/exchange?json:

%answ=[cc=VND].rate

If needed, add a query header to top node level. In our example the authorization key is indicated as header.

⚠ You can use JSON path syntaxt to get values from API response(for example, in ANSWER you can write %var=$.path.to.the.object)

If you don't need to get any data from response, you can use ASYNC requests. This request will execute as async, which don't wait for a response. This will speed up your scenario execution flow.

Click icon to copy this map or open it in