> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/en/app/automations.md).

# Automations

Automations are a visual builder that lets you set up your bot so it reacts to user actions on its own, without you doing anything manually: sending messages, passing data to other systems, changing user information, and more.

{% hint style="info" %}
You'll find this section in the dashboard at <https://app.graspil.com/workflows>
{% endhint %}

## Why you need this

Without automations, you'd have to send messages to every user by hand, or ask a developer to write custom code for every scenario. With automations, you set up a scenario once using a visual, drag-and-drop builder (no code required) — and from then on, the bot keeps running it by itself, continuously, for every user it applies to.

Examples of what you can build:

* A user pays for an order → 5 minutes later, send them a thank-you message with a link to support chat.
* A user signs up but doesn't take any action for 3 days → send them a reminder about the bot.
* Every Monday at 10:00 → send a stats report to your Telegram channel via webhook.
* A user submits a request → automatically create a deal in your CRM.
* A user reaches a certain activity level → set a custom field "VIP" on them, so you can use it later in broadcasts and reports.
* The bot sends a message with buttons — for example, a survey "Did you like the service?" with "Yes" and "No" buttons → depending on which button the user taps, instantly continue with its own branch of the scenario — this is how you can build simple polls, quizzes, and multiple-choice menus (see the buttons section below for details).

## What an automation is made of

Every automation is built from blocks that you connect with arrows on a canvas — much like a flowchart. There are four types of blocks:

| Block         | What it does                                                                              |
| ------------- | ----------------------------------------------------------------------------------------- |
| **Trigger**   | What starts everything. Every automation has exactly one                                  |
| **Action**    | What to actually do (send a message, call a webhook, etc.)                                |
| **Condition** | A fork: if the condition is true, follow one branch; if not, follow another               |
| **Wait**      | A pause before the next step — either for a set amount of time, or until an event happens |

In plain terms: the trigger answers "when should this run?", actions answer "what should happen?", conditions answer "what if I need different behavior for different users?", and wait blocks answer "what if I need to do something not right away, but after some time?".

## How to create an automation

1. Open the **"Automations"** section in the dashboard and click **"Create automation"**.
2. Give it a name (only visible to you — just to tell automations apart) and select the bot it's for.
3. After creating it, you land on the automation's page, where you can see its status, run statistics, and version history.
4. Click the pencil icon — **"Edit in builder"** — to open the visual canvas and build the diagram.

### Building the diagram on the canvas

On the right side of the canvas there's an **"Add block"** panel with three groups: **Triggers**, **Logic**, **Actions**.

1. Start by adding a trigger — it will appear as the first block on the canvas. You can only add one trigger — once it exists, the trigger section in the panel disappears.
2. Add one or more action, logic, or wait blocks, depending on your scenario.
3. Connect the blocks with arrows: grab the output "handle" of one block and drag it to the next one. Each output can only have one outgoing arrow — dragging a new connection replaces the old one.
4. To remove a connection between blocks, click the arrow — a "Delete" button will appear.
5. To configure a block itself, click on it — a settings panel will open (what's in it depends on the block type, see the sections below).

{% hint style="warning" %}
If the diagram has no trigger, no actions, or some blocks aren't connected to each other, you won't be able to publish the automation. The system will show you exactly what needs to be fixed.
{% endhint %}

## Trigger — what starts the automation

When setting up the trigger, choose the **"Launch type"**:

* **"By event"** — the automation runs whenever a user completes one of the selected events (e.g. "payment", "sign-up"). You can pick several events at once — any of them will trigger it. This is the same event list used in reports — see [Event reference](/en/app/reports/events.md) for details.
* **"On a schedule"** — the automation runs on a timer: you specify the **frequency** (every day / once a week / once a month / once a year) and the **launch time**.
* **"Manual launch"** — the automation doesn't run by itself; you trigger it yourself (e.g. for testing).

For "By event" and "On a schedule" triggers, you can also click **"Configure filters"** to narrow down exactly which users the automation applies to — for example, only users on a certain plan or with a certain interface language. This filter works the same way as the broadcast audience filter.

## Actions — what the bot should do

Available actions:

| Action                  | What it does                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Send message**        | Sends the user a Telegram message — text, photo, video, document, etc., optionally with buttons. The text can be personalized by inserting the user's name and other data |
| **Webhook**             | Sends a request to your server or an external service — handy for passing user data into your own system                                                                  |
| **Create event**        | Records a new event in analytics — useful if you want to build a report on how the automation performed                                                                   |
| **Change custom field** | Changes the value of a user's [custom field](/en/app/custom-fields.md) — set a value, or increase/decrease a number                                                       |
| **Integrations**        | Send data to an external service, e.g. create a deal in a CRM (amoCRM, Bitrix24), or send an offline conversion to Yandex.Metrika                                         |

{% hint style="info" %}
For integration actions you need to set up the integration itself in the dashboard beforehand — the action won't work without it. The list of available integrations keeps growing. If you don't see the integration you need, message us — we'll add it within a few days.
{% endhint %}

Text fields inside actions (like the message text) support variables — they're automatically replaced with real user or event data at the moment of sending. For example, if you insert the user's name, every recipient sees their own name.

You can add buttons (an inline keyboard) to a message — for example, for a survey or a menu of choices. When adding a button, pick the **"Continue scenario"** type for it — the button then becomes its own separate output from the "Send message" block: you can drag an arrow from it further down the diagram, just like from a regular block. One tap, one output — a message can have as many "Continue scenario" buttons as you like, each with its own branch. See "Buttons that continue the scenario" below for details.

Buttons of other types (a plain `url` link, or a button carrying custom data for an external integration) aren't involved in automation branching.

### Sending the message in the recipient's language

If your bot has a multilingual audience, you don't need a separate "Condition" branch per language. The "Send message" block has a language switcher above the text field:

1. Click "+" next to the **"Default"** tab and pick a language from the list — it's built automatically from the languages your bot's users actually have.
2. On the new tab, write the text for that language — it's a separate variant, not a copy of the default text.
3. You can add as many languages as you like. The rest of the block's settings (buttons, media, file) stay shared across all languages — only the text/caption switches.

When the automation reaches this block, the bot checks the recipient's Telegram interface language and sends whichever text variant you've set up for it. If there's no variant for that recipient's language, the "Default" text is sent instead. If you never touch the language switcher, nothing changes — everyone gets the same text, exactly as before.

## Condition — different logic for different users

A "Condition" block creates a fork in the diagram: if the condition is true, execution follows one arrow from the block; if it's false, it follows the other arrow (if you've drawn one) — or simply stops.

To configure a condition, click the block and select **"Configure condition"** — this opens the same condition builder used for broadcast audiences: you can check user fields (language, sign-up date, custom fields, etc.), compare them, and combine several conditions with "AND"/"OR".

**Example:** "If the user's custom field 'Plan' is set to 'Premium' → send one message, otherwise → send a different one."

## Wait — a pause before the next step

There are two kinds of wait blocks:

* **Wait for time** — simply pauses for a set amount of time (e.g. wait 1 hour) before moving on to the next block.
* **Wait for event** — pauses until the user completes a chosen event, but no longer than a specified timeout. If the event never happens, execution continues along the timeout path.

**Example use case:** "User places an order → wait for the 'payment' event for up to 30 minutes → if payment happened, send a thank-you; if not, send a reminder about the unfinished order."

## Buttons that continue the scenario

The simplest way to build a poll, quiz, or choice menu is buttons of the **"Continue scenario"** type on a "Send message" block (see Actions above).

1. In a "Send message" block, add a button and pick the **"Continue scenario"** type for it.
2. The block gains a separate output for that button on the canvas — drag an arrow from it to the next block, same as usual.
3. With several such buttons, each has its own output and its own branch: the user sees one message with several buttons, and the scenario continues along whichever branch matches the button they tapped.

{% hint style="info" %}
This kind of button isn't one-shot — it keeps working after the first tap, and the scenario fires again if the user taps it (or another button on the same message) again. This is handy for a persistent menu that can be tapped any number of times.
{% endhint %}

**Example use case:** "The bot sends 'Did you like the service?' with 'Yes' and 'No' buttons → the 'Yes' branch sends a thank-you, the 'No' branch asks for details about the problem."

{% hint style="warning" %}
This is different from a regular "Wait for event" block: there you manually pick a single event and configure a timeout with its own branch, while a "Continue scenario" button creates the branching automatically, without a separate wait block on the canvas.
{% endhint %}

## Saving, testing, and publishing

* Changes to the diagram are saved as a **draft** — you can edit it as many times as you like, nothing breaks until you actually publish.
* The **"Run test"** button (play icon) lets you check how the diagram behaves with test data, without sending anything to real users — useful to make sure everything's configured correctly before turning the automation on for everyone.
* Once everything's ready, click **"Publish"**. From that moment, the automation starts running on its own: it watches for its trigger and runs its actions for every matching user, without any further action from you.
* If there are errors in the diagram (for example, no event selected for the trigger, or an action isn't filled in), the system will show a list of what needs fixing and won't let you publish until they're resolved.

{% hint style="info" %}
A published diagram doesn't change on the fly. If you want to tweak a running automation, your changes are saved as a new draft version — the old version keeps running exactly as before until you publish the new one.
{% endhint %}

## Automation statuses

| Status       | What it means                                                               |
| ------------ | --------------------------------------------------------------------------- |
| **Draft**    | The diagram hasn't been published yet, the automation isn't running         |
| **Active**   | The automation is published and running                                     |
| **Stopped**  | The automation was stopped manually — temporarily inactive, but not deleted |
| **Archived** | The automation has been archived                                            |
| **Error**    | Something went wrong during a run — worth checking your action settings     |

To temporarily turn off a running automation, open it and click **"Stop"**. To turn it back on, publish the version you want active again.

## Configuring concurrent runs

If the same user can trigger the automation again before a previous run for them has finished (for example, with an event-based trigger and frequent events), you can control this behavior via the gear/sliders icon on the canvas:

| Option                 | What happens                                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| **Parallel (default)** | Every run executes independently, even if a previous one for the same user hasn't finished yet |
| **Cancel previous**    | A new run cancels the still-running previous one and starts fresh                              |
| **Ignore new**         | While one run is in progress for a user, new trigger events for them are ignored               |

## Version history and statistics

On the automation's main page (not the builder, but the overview page with its settings), you'll find:

* **Version history** — every saved draft and published version; any of them can be opened in the builder for editing, or published again.
* **Statistics** — how many times the automation has run, how many runs failed, how many unique users it ran for, shown as a chart over a chosen period.
* **Runs (executions)** — a list of recent runs with the user, status, and time; failed runs have a retry button, plus an error log showing exactly which block in the diagram something went wrong on.

## Running an automation for a chosen audience (like a broadcast)

Besides triggering automatically, a published automation can also be run manually for an entire audience of users at once — the same way you'd launch a regular broadcast.

1. Go to the **"Broadcasts"** section → **"Create campaign"**.
2. On the campaign-type step, select the **"Run automation"** card.
3. Build the audience using the same builder as for a regular broadcast (all users, by conditions, by list, etc.).
4. Pick the automation you want from the **"Select a workflow to run"** list — only already-published automations are available here.
5. Launch the campaign — the automation will run for every user in the chosen audience, exactly as if its trigger had fired for them.

This is handy when you want to run an existing scenario (say, a multi-step message chain with conditions and waits) once against a specific list of users, instead of setting up a separate trigger for it.

## Deleting

You can delete an automation from the list ("Automations" → trash icon on the row) or from the automation's own page. Deletion is permanent — it removes the automation along with all its versions and run history.

{% hint style="info" %}
Want to manage automations programmatically from your own system instead of through the dashboard? See the [Automations API documentation](/en/api/automations.md).
{% endhint %}