API Requests

What is the "API Request" block?

The "API Request" block allows the bot to communicate with any external HTTP service—such as your backend, CRM, or database via REST API, or any other service with an HTTP interface. The response is automatically parsed and saved into variables.

Unlike Integrations (which work with ready-made services using templates), the API Request block is universal and fully customizable.

Request Configuration

Example URL with a variable

https://api.example.com/users/{{user_id}}/orders

Example POST request body

{
"name": "{{user_name}}",
"email": "{{user_email}}",
"phone": "{{phone}}"
}

Handling the Response

The API response is saved to the specified variable. If the response is a JSON object, fields are accessible via dot notation:

{{result.status}}      → "status" field in the response
{{result.data.id}}     → nested field data.id
{{result.items.0.name}} → first element of the items array

Response Caching

If the API response does not change frequently, enable caching—the request will be executed once, and subsequent calls will be instantaneous.

The cache is stored at the bot level. If the URL changes (including any variables within it), the cache is not used.

Polling Mode

Some APIs operate asynchronously: a request initiates a task, and the result must be "polled" periodically. For such services, enable polling mode:

1. Enable "Wait for result".
2. Specify the status field in the response (e.g., status).
3. Specify the completion value (e.g., done or completed).
4. The bot will repeat the request at intervals until the field takes on the required value.

Example: Image generation via an external API — a request is initiated, then the bot periodically checks the status and proceeds with the scenario once the image is ready.

Background Process

If request processing might take more than 3 minutes, enable the "Background process" option (available only when polling is enabled).

⚠️ Important: The background process is a blocking operation — all subsequent blocks of the current command will not be executed. Instead, configure a next command that will be triggered automatically once processing is complete.

When the background process is enabled, the webhook handler terminates immediately, and API polling is performed in a background task queue. The workflow resumes from the specified next node once the polling condition is met or attempts are exhausted.

Loader

If "Show loader" is enabled, the bot will immediately send a message with a progress indicator that updates in real-time:

Each of the loader's 10 segments corresponds to 10% of the specified time. For example, if set to 5 minutes: after 2.5 minutes, 5 out of 10 segments will be filled. Once processing is complete, the message containing the loader is automatically removed.

Variables

The API response is saved to the specified variable in the standard format (JSON or file path). All variables accumulated in the workflow prior to the background process launch are preserved and remain available for the next command.

Error Handling

If the request returns an HTTP error (4xx, 5xx) or times out in polling mode:

• The result variable is set to an empty value.
• Use a "Condition" block after the API request to check for a result and route the user along the appropriate path.

Tips

• Always add a "Condition" block after the API request to handle cases where the server is unavailable or returns an error.
• Store API tokens in variables rather than hardcoding them in the URL string; this makes token updates easier.
• Enable caching for reference data (e.g., category lists, exchange rates) to avoid overloading the external API.