API Requests
Basic Information About Requests
Request is an address from one service to another service to receive or send information.
Requests can be made to any third-party service that supports them. If you can't find the API documentation in the public domain, contact support or the system developers.
Botmother can send requests and accept responses only in JSON format. If the system you need does not support JSON, you need to look for a service that changes the request format, or write a processing script in code on the server. You can also use services that replace integration with requests — for example, Zapier
There are many types of requests, we use only the most common ones: GET, POST, PUT, DELETE.
- GET is most often used as an information request. In some cases, it can be used equivalently with other types of requests. For example, in Telegram, you can use both GET and POST for the same requests.
- POST is used to send information and create objects. This method is most often used to create applications, make orders, etc.
- PUT updates the information about the object.
- DELETE deletes the created object.
GET request body can be passed in the URL string, for other requests it is possible only in a special component field.
Basic Information About Responses
Information about an error or about a successful request with or without additional data can be the response to the request.
You can find out more about the answers to request in Wikipedia.
Success and error responses are most often received.
If the request was successful, the code will have a value starting with 2:
- 200 OK — successful request.
- 201 Created — a new resource was created as a result of successful execution of the request.
- 202 Accepted — the request was accepted for processing, but it is not completed.
If the request failed due to an error in the request parameters, Botmother considers it successful, but {{last_request}} object will have an error starting with 4:
- 400 Bad Request — the server detected a syntax error in the client request. This code is used for any errors of this type, if the service developer doesn't nest other values in it.
- 401 Unauthorized — authorization is required to access the requested resource.
- 403 Forbidden - the server understood the request, but it refuses to execute it due to restrictions in access for the client to the specified resource.
- 404 Not Found — the requested resource was not found or does not exist.
If the request failed due to a server error (the request fell due to timeout, the server is unavailable or the body could not be parsed), the bot executes the error screen. In all other cases, the success screen will work. If the response came valid with the status which is not 200, you need to install Fork component after the request and look at the status in the body. Based on this, you can direct it to the desired screen. Server errors start with 5:
- 500 Internal Server Error — it may be any internal server error. This code is used if the developer has not added code to describe this error.
- 501 Not Implemented — the server cannot process the request. For example, you are using a method that doesn't exist.
- 502 Bad Gateway — appears when the server to which you are making a request is actually a buffer between you and another server, it receives an incorrect response from another server.
- 503 Service Unavailable — the server is temporarily unable to process requests. Such errors occur when the server is turned off, does not have access to the Network or it is restricted in access.
- 504 Gateway Timeout — when the server to which you are making a request is actually a buffer between you and another server, it does not receive a response from the other server.
Sending by the GET and POST Method
We will use requests to the Telegram bot API for the example.
When each bot is created it is assigned a unique token of the following type 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
Authorization of requests to Telegram passes through the bot token. This means that the request will be triggered in the bot whose token you specified. For example, when sending a request with a text, you can specify the token of another bot, and then the message will come to it.
All requests in Telegram are created according to the template:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА
API method is the action that the system is supposed to perform in the specified bot.
One of the simplest methods is SendMessage. It sends a text.
Request parameters are mandatory and additional data that specify what action will occur. For example, the parameters of the recipient or the text that will be sent to him.
The required parameters are chat_id and text:
- chat_id is a unique user ID in Telegram. We get it from the variable {{this_user. platform_id}}. To send a message to a specific user, you need to insert the value of his variable.
- text is the text of the message that we are sending.
To transfer spaces in the request URL, you need to replace them with + sign . If you send a text with spaces, it will end at the first space.
For GET request, API method and parameters are passed to the request URL. The parameters are separated from API method by a question mark. The parameter value is sent after the equal sign. The parameters are separated from each other by & sign.
We create a GET request template:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА_API?параметр1=значение1&параметр2=значение2 We substitute the method and parameters for sending the text:
https://api.telegram.org/bot<token>/sendMessage?chat_id=значение1&text=значение2
We insert the values of the token and parameters to get a working path (URL) of GET request:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id=123456&text=Привет+из+бота! Now let's try to make the same request, but using POST method.
The request parameters and their values make up the request body. Therefore, in the URL string, we write only:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА
For POST method, only API method is passed to the URL, the parameters are sent in the request body in JSON format.
JSON is one of the data formats. It consists of key-value data pairs. The key is the name of the parameter, the value is the value of the parameter (it can be defined or variable).
To make a body with our parameters, we specify them in JSON format:
{
"chat_id": "123456",
"text": "Привет из бота!"
} It is important to mind the syntax. If you forget to put at least one character, the request will not work. This is the most common error when sending requests.
We insert GET request to the screen in the constructor:
* required fields
We insert Post request to the screen in the constructor:
* required fields
For testing, you can try to delete the previous message using deleteMessage method.
Required parameters:
- chat_id is the unique identifier of the user in the bot. We get it as the main variable {{this_user. platform_id}}.
- message_id is a unique identifier of the message, that is located in {{last_telegram_message_id}} variable.
Response Processing — Object
For example, we will use the resource https://www.cbr-xml-daily.ru.
We select a request in JSON format in it:
https://www.cbr-xml-daily.ru/daily_json.js
We open it as a regular link in the browser and get a response in JSON format.
To make the answer easy to read, install the extension on the browser. For Google Chrome, you can use JSON Formatter.
For example, we want to know the cost of 1 Belarusian ruble. We find the part where BYN value is output and compose a variable.
The response to the request is located in {{last_request}} object.
To output a variable inside the text, input it inside curly brackets:
