How to make API call from Ideta's app

The purpose of this documentation is to present the API call configuration bubble, and to help you set up your API calls from Ideta's chatbot to an external tool.
In general, we recommend that you always test your API calls before deploying them on a channel, in order to ensure the validity of the settings.

You can test our APIs in Postman

Request configuration

Authentication key

In the "Request headers" part, it is possible to enter a header of your choice.
If the authentication method of the called API differs from the one proposed above, please contact the support.

API URL (required)

The URL of the targeted API.
You have the possibility to format your url with dynamic values from the conversation data.
Please note!  To be valid, the URL must be entered without spaces.

Request Type (required)

To find out what type of request you should send, you can refer to the documentation of the targeted API.
The most common types of requests are:

• GET - for retrieving data
• POST - for sending data

Body Format

In a POST, PUT or PATCH request, you can attach a body to your request, containing the data you want to send. As for the URL, this data can come from the conversation.
‍
The request bodies are in TEXT, JSON (Javascript Object Notation) or XML format.

The JSON format requires the following syntax standards to be respected:

• The request body starts with '{' and ends with '}'.
  
• Each property and value name is enclosed in double quotes.
  Example -> "property "
  
• Properties and values are separated by a colon.
  Example -> "name": "fabien "
• Each set "property": "value" is separated from the next by a comma.
  Example -> "property1": "value1", "property2": "value2"

Linking bubbles

Once the request has been made, the "next Bubble" allows you to redirect to the next part of the conversation.

If an error occurs during the process (API not available, authentication error, error in storing the response, etc.) the "Fallback Bubble" redirects to an appropriate conversation bubble to inform the user.

Timeout (required)

Temps d’attente maximum après lequel la conversation est automatiquement redirigée vers la Bulle de secours.

• The value to enter is an integer expressed in milliseconds. 
• The recommended value is 2000 ms (2 seconds).
• The maximum allowed value is 10000 ms (10 seconds)
• If the maximum duration is not sufficient, it is possible to use background actions.

Storage and use of response data

If you want to retrieve data from the API response you can enable the Store Response option to access the rest of the form:

Storage key (required)

This is the key on which the response data will be stored.

• It must have properties under which the desired values will be stored.
  
• For each property of the storage key, you can describe the path to the desired value in the "Data structure".
  
• The key must have one or more properties. It is not necessary to fill in all properties, but you must set at least one to have a valid storage.
• It can be an object key or a list of objects.
  
• The paths must be entered without spaces.
  

Storing in an object

Assuming we want to retrieve the values of "city" and "closing_hours". The properties of the key can be named differently from the properties referred to in the answer.
‍
The storage key will be configured as follows:

The settings will be as follows:

Using it in your conversation

Once the API call is successful, you can use the stored data like any other key in the following bubble settings.

Storing in a list

Assuming that we want to retrieve the list of products keeping only the name and the price, the storage key will be configured like this:
To retrieve the list containing the targeted data, you must also define the Path of the list (mandatory). This field indicates its position within the response.

Using it in your conversation

Storing a list after an API call can be useful to automatically generate quick responses, carousels or lists.