Categories
Getting started Billing Bot settings Platform connection Text Buttons Mediafiles Other components Payment systems Growth tools Broadcasting Communication with users Statistics Users FAQ Requests and integrations Notifications Variables Variables 2.0 and helpers Regular expressions Events Cases Problem solving

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 the article.

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. This errors 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 method

Creating URL for GET request

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:

  • 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.

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!

Component setup

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.

6. If the API requires, add additional Request headers in the component drop-down menu. Don't delete the default headers.

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

Sending by the POST method

Creating URL for POST request

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}}.

Component setup

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

Deleting a message using a POST request

Video tutorial ↓

To test the POST method, you can try to delete the previous message using the 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, located in the variable {{last_telegram_message_id}}.

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.

Video tutorial:

The way you can delete the last message from the user

Video tutorial ↓

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": "{{lastUpdate.update.chat.id}}",
"message_id": "{{lastUpdate.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.

Video tutorial:

How to delete any message with a POST request

Video tutorial ↓

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:

  • 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, located in the variable {{last_telegram_message_id}}.

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.

Video tutorial:

Send a sticker using a POST request

Video tutorial ↓

Let’s send a sticker to the chat using the sendSticker 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}}.
  • sticker is the unique identifier of the sticker. You can find out the sticker ID by sending a sticker to bot Sticker ID.

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.

Video tutorial:

Sending a request to GPT with a POST request

Sending a request to GPT with a POST request

Let's move on to GPT with a POST request. We will output the response from the neural network in the bot.

The required parameters:

  • model — the language model that GPT responds to, we recommend using text-davinci-003
  • prompt — the text to send to GPT. The text can be written to a variable in advance and output in the request body
  • max_tokens — the maximum number of characters in the response from gpt. The value can be between 16 and 4000

Here are the steps to create a POST request to GPT in the builder:

1. Add the Request component to the screen.

2. Select the Request Method - POST.

3. Specify the request URL.

The request path (URL) would be as follows: 

https://api.openai.com/v1/completions

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: 

    {
      "model": "text-davinci-003",
      "prompt": "{{prompt}}",
      "max_tokens": 400
    }

7. Add an additional request header: 

Key: Authorization
Value: Bearer 12345xQWERTY, where 12345xQWERTY is the token that you received in OPEN AI.
If access from your country is blocked, use a VPN.

You can get a token this way:

Don't delete the default headers.

8. Set the Variable Name for the response body if you need to record the response from the server not in last_request, where the response comes by default.

9. In order for the response from GPT to come directly to the bot, add a message where the variable with the response will be displayed. If you doesn’t change the variable for the default response, add this template: 

{{last_request.choices.[0].text}}

10. After the response, you can add Rewind to the same screen to avoid restarting the script for a new access to GPT.

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.

↑