Configuration examples (REST)
Example 1: Weather Web Service Configuration
This section describes the steps to configure a REST weather web service to automatically respond to user requests. You can use the openweathermap service (https://openweathermap.org/api) for this purpose. You will need to create an account to obtain an API key.
To carry out this configuration, you must perform the following steps:
Creating and configuring a web service
1 - Go to Contents > Web Services.
2 - Click on Add and then select Rest Web Service.
3 - Fill in the following fields in "Web Service Configuration".
Name : "Meteo"
HTTP Method : GET
Type de réponse : JSON
4 - Fill in the following fields in "Parameters".
APPID: The parameter is provided by WorldWeatherOnline after creating an account.
lang: fr
q: ${capture.ville meteo}
5 - Click on "Add" in the "Result Variables" category and add the following two variables:
Attention: variable names are free to choose but must be consistent with what is indicated in the knowledge. Variable names must consist of alphanumeric characters or underscore characters and start with a letter. They are also case-sensitive.
6 - Change the JSON output format with the following values:
7 - Test the configuration of your web service.
with the test value 'Paris' in the parameters:
Creation of the associated knowledge
The objective now is to create knowledge to provide data to the web service and deliver it to users.
Configure the query:
User's phrase : The sentence should resemble a request to know the weather in a given city. The crucial point in this sentence is not to forget the variable. In our example, the variable is called "ville" and it is Alphanumeric type.
1 - Create a knowledge "What is the weather in" and then click on "T".
2 - Search for the variable "Ville"
3 - Click on the city group and name the variable "villemeteo"
4 - Click on "update"
5 - Click on "Create" to create the knowledge
Configure the response
The response given to the user will display the temperature and the city understood by the system to identify any discrepancies.
It is important to note that:
Variables retrieved from the web service are structured as follows: ${callapi.WebServiceName.variableName}
Variables retrieved from the dialogue box are structured as follows: ${capture.VariableName}
For more detail :
Example 2: Use the web service in a condition
Web services can be used in knowledge but also in conditions. Reuse the weather service to find out if it's hot or cold in a city. In our example, it is considered that it is hot at more than 20 degrees and cold in the opposite case.
1 - Create a new knowledge to answer.
2 - Then create the two possible answer with a new condition that you leave blank for now:
Once the knowledge part is prepared, you have to create a new condition that will use the web service. To do so, visit the Knowledge > Advanced > Context conditions page.
1 - Click Add a condition and create the associated condition:
Note that the operation is of Math expression type and the value must be a correct expression with x the variable returned by the expression in Condition. Here, we must check that callapi.TestWeather.Temperture > 20.
Finally, we must use this new condition in the knowledge we have created. To do so:
1 - Edit the condition, select IsTempertureGreaterThan20
2 - Click Update.
You can now test your knowledge with the bot.
Example 3: Web service configuration - IP address
Here we will use the httpbin web services: http://httpbin.org/ and specifically the IP web service that returns the IP of the requesting user.
Creation and configuration of the web service
1 - Create a web service in REST mode.
2 - Enter the JSON code in the Result Variables section :
3 - Enter the variable "IP" by clicking on "add". You can add as many variables as you want.
4 - Then click on Save.
5 - Click the Test button to verify that the web service is operational.
If there are no errors, the IP will be returned to you; otherwise, an ERROR element may appear. It's important to note that HTTPS web services may not work. If that's the case, simply remove the "S" to use HTTP protocol only.
Creation of the associated knowledge
Next, go to the Content > Knowledge page and create a new knowledge entry like the example below:
You can then test your knowledge by asking your bot through the test dialogue box. Ask it the question "What is my IP?" and the bot will return your IP address.
Example 4: Sending multiple attachments
For example, if your bot offers to create an IT support ticket, you can allow the user to add one or more attachments during the ticket creation process.
There are two different ways to configure your webservice for sending multiple attachments:
Configuration via the request Body (JSON Format)
In the Body of your POST request, use the ${DialogAllLastFilesUploaded()} function. The three parameters you pass in parentheses define the key names that will appear in the final JSON.
Parameter 1: Key name for the file name.
Parameter 2: Key name for the content type.
Parameter 3: Key name for the base64 content.
Example of your Web Service Body:
At runtime, the engine replaces the variable with an array of objects. Here is what the JSON stream sent to your server looks like if the user uploaded two files:
Configuration via a parameter (Multipart Format)
This second approach is ideal if the destination server expects a request in standard file upload format (multipart/form-data) rather than a JSON stream. It has the advantage of being automatically generated by the system.
How to configure this method? Instead of manually building the Body of your request, simply use the function directly in your Web Service parameters.
The function to use: Simply enter
${DialogAllLastFilesUploaded()}.Please note: Unlike the Body method, the parentheses must remain empty. It is not necessary to define key names.
What happens during execution? The tool takes over and formats the request for you. It automatically generates a multipart/form-data body, the web standard for transferring attachments.
To structure this transfer, the system creates its own unique separation identifier (called a boundary) allowing the destination server to clearly distinguish each sent file.
The generated request Header will look like this:
Attachments sent by users are accessible from the relevant conversation via a token-secured link.
In the event of conversation purging, anonymization, or encryption, transmitted attachments are included: they will no longer be accessible according to the defined purging, anonymization, or encryption criteria.
Example 5: Sending a single attachment
Sending an attachment to a web service assumes that an attachment has been uploaded by the user during the conversation.
If multiple attachments are uploaded during the same conversation, the attachment uploaded during the most recent interaction will be the one sent to the web service (this allows the user to change the attachment in case of a selection error from the chatbox).
The data of the attachment to be sent is accessible using the following three keys:
${DialogLastFileUploadedContent()}${DialogLastFileUploadedContentType()}${DialogLastFileUploadedName()}
Before the edge_2025-12-09 version, the system used different variables.
These variables are still functional but only retrieve the first file sent and are no longer updated. It is recommended to use the new function to handle multiple uploads.
The first keyword refers to the file content, the second to its type, and the third to its name.
In the "Body" area, these three keys can be used as part of JSON content; the value of DialogLastFileUploadedContent will be Base64 encoded.
In the "Parameters" area, only the ${DialogLastFileUploadedContent()} key is required.
When present, the corresponding file will be sent to the web service as multipart/form-data, along with its associated metadata (file name and content type).
If the "Body" area is used to send a file to a web service, it does not make sense to also use the "Parameters" area for this purpose, and vice versa.
Last updated