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 request body can be passed in the URL string, for other requests it is possible only in a special component field.
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 the article.
Success and error responses are most often received.
If the request was successful, the code will have a value starting with 2:
If the request failed due to an error in the request parameters, Botmother considers it successful. This errors starting with 4:
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:
We will use requests to the Telegram bot API for the example.
1. Add the bot token to the URL request.
All requests in Telegram are created according to the template:
https://api.telegram.org/bot<token>/METHOD_NAME
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.
So far, the URL will be like this:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/METHOD_NAME
Where instead of 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 is your bot token.
2. Add the API method.
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.
After inserting the API method, our template looks like this:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage
3. Add the request parameters..
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:
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.
4. Form a GET request template.
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?parameter1=value1parameter2=value2
Instead of parameter1, add chat_id, and output the value1 from the variables {{this_user.platform_id}}.
If necessary, a particular value can be specified in value1.
Instead of parameter2, add text, in value2 write the text that should come to the bot.
The GET request URL is ready:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id={{this_user.platform_id}}&text=Hello+from+bot!
1. Add Request component to the screen.
2. Select the Request method — GET.
3. Specify the Request URL.
4. Specify the Screen that will be executed when the request is successfully executed.
5. Specify the Screen that will be executed when the request fails.
7. Set the Name of the variable for the body of response if you need to write the response from the server not to last_request, where the response comes by default.
8. Set the Name of the variable for a status code of response if you need to write the response from the server not in last_request_status_code, where the response comes by default.
9. 10. Set the Name of the variable for the headers of response if it is assumed that important data will come in the headers, for example, authorization tokens, cookies, HMAC signature or other data that may be required further for use in the bot.
10. Expand the component settings to continue.
11. Check the boxes which Request status codes will be considered successful and which ones will not.
12. To use the data for authorization via http basic authentication, check Use HTTP authorization box.
13. Check Encode request body box if you need to pass parameters according to the Unicode standard.
14. Check Skip HTTPS-cert check box if you have problems with the validity of the certificate. The bot will continue to work, but we recommend to fix problems with the certificate as soon as possible
Since in the POST request, the request parameters and their values make up the request body, in the URL string remains the following:
https://api.telegram.org/bot<token>/METHOD_NAME
Where <token> is the bot token where the request will be triggered </token>
Token example: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
Leave the name of the method, as in the previous example — SendMessage.
We get a URL of this type:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage
Do not add parameters in the URL, as in the GET request.
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": "{{this_user.platform_id}}", "text": "Hello from bot!" }
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.
You can wrap strings using \n, but such characters break JSON. To prevent JSON from breaking, you need to escape in this way: /\n. But this will not work if we send a text from the user in the var variable. In this case, you need to use escapeJsonEntities helper in this way: {{escapeJsonEntities var}}.
1. Add the Request component to the screen.
2. Select the Request method — POST.
3. Specify the Request URL.
4. Specify the Screen that will be executed when the request is successfully completed.
5. Specify the Screen that will be executed when the request fails.
6. The Request body for the POST method is specified if the API requires it. It is supported only in JSON format.
7. If the API requires, add additional Request headers in the component drop-down menu. Don't delete the default headers.
8. Set the Name of the variable for the body of response if you need to write the response from the server not to last_request, where the response comes by default.
9. Set the Name of the variable for a status code of response if you need to write the response from the server not in last_request_status_code, where the response comes by default.
10. Set the Name of the variable for the headers of response if it is assumed that important data will come in the headers, for example, authorization tokens, cookies, HMAC signature or other data that may be required further for use in the bot.
11. Expand the component settings to continue.
12. Check the boxes which Request status codes will be considered successful and which ones will not.
13. To use the data for authorization via http basic authentication, check Use HTTP authorization box.
14. Check Encode request body box if you need to pass parameters according to the Unicode standard.
15. Check Skip HTTPS-cert check box if you have problems with the validity of the certificate. The bot will continue to work, but we recommend to fix problems with the certificate as soon as possible
To test the POST method, you can try to delete the previous message using the deleteMessage method.
Required parameters:
Create deleteMessage POST request in the builder:
1. Add Request component to the screen.
2. Select the Request method — POST.
3. Specify the Request URL.
The request path (URL) will look like this:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/deleteMessage
Where 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 is your bot token.
4. Specify the Screen that will be executed when the request is successfully completed.
5. Specify the Screen that will be executed when the request fails.
6. Add the Request body. The body is supported only in JSON format.
{ "chat_id": "{{this_user.platform_id}}", "message_id": "{{last_telegram_message_id}}" }
7. If the API requires, add additional Request headers in the component drop-down menu. Don't delete the default headers.
8. Set the Name of the variable for the body of response if you need to write the response from the server not to last_request, where the response comes by default.
9. Set the Name of the variable for a status code of response if you need to write the response from the server not in last_request_status_code, where the response comes by default.
10. Set the Name of the variable for the headers of response if it is assumed that important data will come in the headers, for example, authorization tokens, cookies, HMAC signature or other data that may be required further for use in the bot.
11. Expand the component settings to continue.
12. Check the boxes which Request status codes will be considered successful and which ones will not.
13. To use the data for authorization via http basic authentication, check Use HTTP authorization box.
14. Check Encode request body box if you need to pass parameters according to the Unicode standard.
15. Check Skip HTTPS-cert check box if you have problems with the validity of the certificate. The bot will continue to work, but we recommend to fix problems with the certificate as soon as possible.
Now the last message will be deleted from the dialogue with the bot in the messenger, if you set such a request in the builder immediately after the message.
All parameters will be the same as when deleting the last message from the bot, except for Request Body.
The request body will be as follows:
{ "chat_id": "{{last Update.update.chat.id}}", "message_id": "{{last Update.update.message_id}}" }
The request should be triggered immediately after the message from the user comes, for that you need to add a component waiting for user input before the request.
The components could be Fork, User Input, or Rewind with the active checkbox "Stop the bot after rewinding to the next message from the user" should lead to the screen with the request.
The deleteMessage method can be used to delete any message from the bot.
To do this, overwrite {{last_telegram_message_id}} of the component to be deleted to another variable using Variable
Record component.
In Name field, specify a new variable name, and in Value field, enter {{last_telegram_message_id}}.
In our example, the new name for the variable with the message is dlt.
Later we will add it to the deletion request body in double curly brackets: {{dlt}}.
For a clear example of deleting any message from the bot, and not just the last one, as in the previous example, we will add a screen with a request after all messages.
After writing the screen ID to a variable, we will issue a request to delete this screen.
The required parameters:
Let’s create deleteMessage POST request in the builder:
1. Add Request component to the screen.
2. Select Request Method — POST.
3. Specify the request URL.
The request path (URL) would come out that way:
https://api.telegram.org/bot12345/deleteMessage
Where 12345 is your bot token.
4. Specify the Screen that will be executed when the request is successfully executed.
5. Specify the Screen that will be executed when the request fails.
6. Add Request Body. The body is supported only in JSON format.
Don't forget to add our overwritten variable to message_id.
{ "chat_id": "{{this_user.platform_id}}", "message_id": "{{dlt}}" }
7. If API requires, add additional request headers in the component drop-down menu. Don't delete default headers.
8. Set the variable name for the response body if you do not need to write the response from the server to last_request, where the response comes by default.
9. Set the variable name for the response code if you do not need to write the response from the server in last_request_status_code, where the response comes by default.
10. Set the variable name for the response headers if it is assumed that important data will come in the headers. For example, authorization tokens, cookies, HMAC signature or something else that may be required further for use in the bot.
11. Expand the component settings to continue.
12. Check the boxes which response statuses will be considered successful and which ones will not.
13. To use the data for authorization via http basic authentication, check Use HTTP authorization box.
14. Check Encode request body box if you need to pass parameters according to the Unicode standard.
15. Check Skip HTTPS certificate verification box if you have problems with the certificate validity. The bot will continue to work, but we recommend to fix problems with the certificate as soon as possible.
If everything is done correctly, the message with message_id we overwrote and then added to the request body will be deleted.
Let’s send a sticker to the chat using the sendSticker method.
Required parameters:
Let’s create a sendSticker POST request in the builder:
1. Add
Request component to the screen.
2. Select the
Request method — POST.
3. Specify the
Request URL.
The request path (URL) will look like this:
https://api.telegram.org/bot12345/sendSticker
Where 12345 — is your bot token.
4. Specify the
Screen that will be executed when the request is successfully completed.
5. Specify the
Screen that will be executed when the request fails.
6. Add the
Request body. The body is supported only in JSON format.
{ "chat_id": "{{this_user.platform_id}}", "sticker": "12345" }
Where 12345 is the ID of the sticker being sent.
7. If the API requires, add additional
Request headers in the component drop-down menu. Don't delete the default headers.
8. Set the
Name of the variable for the body of response if you need to write the response from the server not to last_request, where the response comes by default.
9. Set the
Name of the variable for a status code of response if you need to write the response from the server not in last_request_status_code, where the response comes by default.
10. Set the
Name of the variable for the headers of response if it is assumed that important data will come in the headers, for example, authorization tokens, cookies, HMAC signature or other data that may be required further for use in the bot.
11. Expand the component settings to continue.
12. Check the boxes which
Request status codes will be considered successful and which ones will not.
13. To use the data for authorization via http basic authentication, check
Use HTTP authorization box.
14. Check
Encode request body box if you need to pass parameters according to the Unicode standard.
15. Check
Skip HTTPS-cert check box if you have problems with the validity of the certificate. The bot will continue to work, but we recommend to fix problems with the certificate as soon as possible.
Now the last message will be deleted from the dialogue with the bot in the messenger, if you set such a request in the builder immediately after the message.
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.