Integrations

Integration module gives the possibility to integrate with external API for enhancing bot's knowledge. It might be useful for providing current data and connecting bot to external databases.

💡

After setting up an integration with Integrations module, use Integration block to add it to your bot's flow.

How to use integration in bot?

To be able to use existing integration, you need to add 2 blocks to the bot's flow:

• Integration block where the integration details need to be filled

• Say block (or other) that will show the result of the triggered integration. To use the integration you need to add {memory.XXX} where XXX is the name of the integration output.

Main view

The main view lists all created integrations.

Create/Edit integration

• Name - unique name of the integration.
• Base URL - common URL of the integration's endpoint.
• Custom request timeout in seconds - maximum allowed time in which request has to be completed.
• Authorization headers - global headers, which are added to each one of the requests.

Add/Edit request

Basic information

• Name - unique name of the request.
• Path - base URL + path defines the endpoint of the request.
• Method - four HTTP request methods are supported: GET, POST, PUT, and DELETE.

Input values

• Body - body of the request in JSON.
• Headers - key-value pairs of headers added to the request.
• Query parameters - key-value pairs of query parameters. Example is described below.

Example

Let's imagine, that we would like to use the HTTP service https://api.open-meteo.com/v1/ to retrieve weather data for given latitude and longitude. Such data is available under the endpoint forecast ① for GET method ②. It's required to provide 3 parameters: longitude, latitude, and enable current weather. Request with those parameters would look like https://api.open-meteo.com/v1/forecast?latitude=your_lat&longitude=your_long&current_weather=1. Flag current_weather has to be set to 1 to get weather data. In order to parametrize latitude and longitude, it is possible to do it via Query parameters or directly in Path. Former requires defining key-value pair, where key is used in endpoint and value is assigned to it. So, in our example, it would be:

and then lat and long values can be assigned.

Latter requires adding query parameter inside Path ①, so it would look like https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={long}&current_weather=1.

🚧

Value

Remember to put value inside curly brackets {} and name value only with alphanumeric characters.

🚧

POST request

When creating a POST request, make sure that the header with Content-Type is set.

JSON body

If you want to add parameters to JSON body in request there is different behaviour for single and double bracket{}

{  
  "role": "user",  
  "content": "Some text: value provided by user"  
}

In "JSON" mode there are two ways of defining input parameters:

• with single braces: {someParameter} - it produces JSON node
• with double braces: {{someParameter}} - it produces escaped string

So correct usage would be:

{  
  "role": {someParameter},  
  "content": "Some text: {{someParameter}}"  
}

Take a look at example usage below:

Output values

It is possible to retrieve data from the output and assign it to the given name. To that end, it is required to set a Json path as a chain of nested fields.
Let's imagine, that as an output for the aforementioned request we received the following JSON

{
  "current_weather": {
    "temperature": 21.8,
    "windspeed": 15.7,
    ...
  },
  ...
}

and we want to retrieve the temperature and windspeed fields, so we need to put current_weather.temperature① and current_weather.windspeed ②under the JSON path and give it some arbitrary name, under which the retrieved values will be available.

Testing

Testing gives a possibility to test a defined request with users' values. If a request is correctly defined, then the following fields will be displayed:

• Response - includes the response of the tested request.
• Parameters - success field is displayed by default and optionally Output values defined by the user are displayed.

Switching to View status and request data shows additional information, like Status code, Request, and Body.

Useful Status codes:

• 200 OK - the request succeeded.
• 400 Bad Request - the server couldn't handle a request, because of some client error.
• 404 Not Found - the server can not find the requested resource (probably an invalid URL).
• 500 Internal Server Error - the server has encountered a situation it does not know how to handle.

For more status codes and a thorough explanation, please refer to Mozzila's documentation.

Let's assume that we would like to test our request and get weather data for Gdansk (54.35, 18.65). To this end, we need to fill in latitude and longitude parameters and hit the Test button.