> 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/event-rules.md).

# Event Rules

Event Rules is a builder that lets you process a bot event before it ever reaches analytics or the conversation history: hide sensitive data, register a conversion by keyword, write a value into a user's custom field, or ignore an event entirely.

{% hint style="info" %}
Available in your dashboard: <https://app.graspil.com/event-rules>
{% endhint %}

## Why you need it

* The bot's message says "Payment of 990 USD" → automatically register a conversion with the amount and currency extracted from the text, with no code changes on your bot's side.
* Right before asking a user to send a one-time token or password — hide their next message in the conversation history, so sensitive data never ends up stored in the chat log.
* When a user record is created or updated, wipe first name, last name, username and bio — for privacy.
* A user writes "buy" — register it as a conversion right away, without waiting for a dedicated event from a developer.
* Keep the bot's internal service messages (tagged e.g. `[service]`) out of analytics.
* Write a value straight from a message into a user's custom field, so you can use it later in segments, broadcasts and automations.

## How this differs from Automations

[Automations](/en/app/automations.md) react to events that have already been stored, and talk to the user — sending messages, waiting, calling webhooks.

Event Rules run one step earlier — the moment raw data first comes in, before the event lands in analytics and before a message is written to the conversation history. They don't send messages to the user; instead they decide **how** that raw event gets stored: as-is, with parts of it hidden, as a registered conversion, or not stored at all.

## What a rule consists of

Every rule has three parts:

| Part           | What it defines                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Event type** | Which bot event to react to (an incoming message, a button click, the bot sending a message, etc.) — pick exactly one |
| **Conditions** | Under what circumstances the rule fires (optional — with no conditions the rule fires on every such event)            |
| **Actions**    | What to do with the event once conditions match — you can add several, they run in order                              |

## How to create a rule

1. Open **"Event Rules"** and click **"Create rule"**.
2. At the top of the page there's a **"Ready-made rule examples"** row — click any example to instantly apply a ready template and adjust it to your needs, instead of building from scratch.
3. Walk through steps 1–4 (event type → name/priority → conditions → actions), described below.
4. Click **"Save"**.

{% hint style="info" %}
Unlike automations, Event Rules have no separate draft and publish step. If the "Enabled" toggle is on, the rule starts applying immediately after you save.
{% endhint %}

## Step 1. Event type

The event type decides which data is available to check in conditions, and what kind of "raw" event the rule reacts to:

| Event type               | Fires when                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User sent a message**  | On any incoming message from the user — text, photo, document, etc.                                                                                                                               |
| **Inline button click**  | When a user taps an inline button under a bot message (callback)                                                                                                                                  |
| **Bot sent a message**   | When the bot sends a message, photo, video, etc. to a user                                                                                                                                        |
| **Bot edited a message** | When the bot changes the text or caption of an already-sent message                                                                                                                               |
| **User profile save**    | On creating or updating a user record. Only for hiding personal data and writing custom fields — conditions and most actions aren't available for this type; the rule fires on every profile save |

## Step 2. Name and priority

* **Name** is visible only to you — for telling rules apart in the list.
* **Priority** is a number that controls the firing order. The lower the number, the earlier the rule is checked. This matters when several rules are set up for the same event: rules with an action from the "Skip / ignore" group (see below) stop further processing — rules that come next in order won't run.
* **Enabled** is a toggle to temporarily turn a rule off without deleting it.

## Step 3. Conditions

Conditions are a gate: the rule applies only if the conditions match. With no conditions, the rule fires on every event of the chosen type.

Conditions are combined into groups:

| Group                    | Logic                                   |
| ------------------------ | --------------------------------------- |
| **All conditions (AND)** | Every condition in the group must match |
| **Any condition (OR)**   | At least one must match                 |
| **NOT**                  | The condition must be false             |

Groups can be nested inside each other ("Add nested group") to build arbitrarily complex logic.

Inside a group are individual checks. Which checks are available depends on the selected event type:

| Check                                       | What it does                                                                                  |
| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Text contains**                           | The message text (or media caption) contains the given substring; can be set case-insensitive |
| **Text matches regex**                      | Full regular expression over the message text (advanced)                                      |
| **Message type (photo/video/...)**          | Filters outgoing bot messages by type — e.g. photos only, documents only                      |
| **Button data contains**                    | Substring in the tapped inline button's data (`callback_data`)                                |
| **Callback JSON field equals / not equals** | If `callback_data` is JSON, looks up a field by path and compares the value (advanced)        |
| **Event type ID is in list**                | Match by numeric event type IDs from the system reference (advanced)                          |

{% hint style="info" %}
The **"Advanced options"** toggle on the conditions step reveals technical checks (regex, working with JSON inside a button, etc.) — for most scenarios a simple "Text contains" check is enough.
{% endhint %}

## Step 4. Actions

You can add one or several actions — they run in order, top to bottom. Actions from the "Skip / ignore" group stop further processing of the event.

### Skip / ignore

| Action                      | What it does                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Don't save this event**   | The event won't appear in analytics, but related messages are still stored in the conversation history |
| **Don't save related data** | The message won't be stored in the conversation history, but the analytics event remains               |
| **Ignore event entirely**   | Fully stops processing: no event, no storage. Use with care                                            |

### Conversions

| Action                  | What it does                                                                                                                                                                                                                                                   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Register conversion** | Registers a [target/conversion](/en/api/send-event.md) — e.g. a payment or a signup. You provide a target ID; the amount and currency can be set as a fixed value or extracted from the text with a regular expression (the first capture group is the number) |
| **Replace event type**  | Stores the event under a different event type ID — useful for reclassification                                                                                                                                                                                 |

### User profile

These actions are only available for the "User profile save" event type:

| Action                    | What it does                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Write to user profile** | Writes an arbitrary value into the specified [custom field](/en/app/custom-fields.md) of the user, by key |
| **Hide personal data**    | Clears the selected profile fields (first name, last name, username, bio) — for privacy                   |

### Privacy

| Action                          | What it does                                                                                                                                                                                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Don't save the next message** | Arms a "wait window": the next message of the chosen direction in this chat is stored in the conversation history not as-is, but with a placeholder instead of the text. Analytics is unaffected — only the raw conversation history is hidden |

For the "Don't save the next message" action, you set:

* **What to hide** — the next incoming message, the next outgoing message, or both directions (whichever arrives first triggers it);
* **Wait window (minutes)** — how many minutes to wait for that message, up to 30. If nothing arrives in time, the window closes on its own without hiding anything.

This is handy on a "Bot sent a message" rule with a condition like "text contains 'please send your token'" — that way the user's reply containing sensitive data never ends up stored in the conversation history.

## Ready-made examples

The rule creation page has a row of clickable templates — they instantly fill in a configured rule that you can then adjust to your needs:

| Example                                          | What it does                                                                                                             |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Catch payment in outgoing message**            | When the bot says "Payment of X USD" — registers a conversion with the amount and currency extracted from the text       |
| **Edit of outgoing message containing 'test2'**  | When the bot edits its own message and the new text contains "test2" — ignores it in analytics                           |
| **Hide first/last name/username from analytics** | Wipes personal data on profile save                                                                                      |
| **Don't save service messages**                  | Ignores outgoing messages tagged with `[service]` in the text                                                            |
| **Conversion when user writes 'buy'**            | When a user sends a message containing "buy" — registers a conversion                                                    |
| **Don't save the reply containing the token**    | When the bot asks the user to send a token — the next incoming message in this chat is stored as hidden instead of as-is |

## Managing rules

The main "Event Rules" list shows, for each rule: its name, what it reacts to, which actions it runs, its priority, and its status.

* The toggle in the **"Status"** column enables or disables a rule directly from the list, without opening it for editing.
* The pencil button opens the rule for editing.
* The trash button deletes the rule permanently.

{% hint style="warning" %}
If several rules apply to the same event, they're checked in order of priority (lowest first). Keep this in mind when setting up multiple rules for the same event type — a lower-priority rule with a "Skip / ignore" action can stop the following rules from being checked.
{% endhint %}