> 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/reports/events.md). # Event reference This page lists all **standard events** that graspil creates automatically, without any configuration on your side. In addition to these, you can create your own custom events — via the [API](/en/api/send-events.md), [triggers](/en/app/actions.md), [automation](/en/app/broadcast.md), the [mini app](/en/connect-bot/mini-app.md#svoi-sobytiya), or [targets/conversions](/en/api/send-event.md). Those are not listed here, since they are unique to each product. {% hint style="info" %} For some events (e.g. a button tap, a text command, an emoji reaction) the event name is **dynamic** — instead of a fixed `event_name`, the actual value is used (the button text, the command name, the emoji character, etc). These cases are marked separately in the tables below. {% endhint %} *** ## Bot events — user lifecycle Basic events that reflect how a user interacts with the bot in a private chat: first launch, repeat launch, blocking, and return. | Event | When it fires | | -------------------------- | ----------------------------------------------------------------------------------- | | `new_user` | The user sent `/start` to the bot for the first time | | `start_repeat` | A user who already exists in the bot sent `/start` again (e.g. via a new link) | | `user_left` | The user blocked the bot | | `user_return` | A user who previously blocked the bot unblocked it | | `connected_website` | The user connected a website/widget for the first time (via `write_access_allowed`) | | `connected_website_repeat` | The user reconnected the same website/widget | ## Channel and group events The same kind of events, but for users of a channel or group the bot administers. | Event | When it fires | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_chat_new` | The user joined the channel/group for the first time | | `user_chat_return` | The user rejoined the channel/group after previously leaving it | | `user_chat_left` | The user left the channel/group on their own | | `user_chat_kicked` | The user was removed from the channel/group by an admin | | `chat_member_` | The member's status changed to anything else (e.g. `chat_member_administrator`, `chat_member_restricted`) — `` is substituted dynamically | | `channel_post` | A new post was published in the channel | ## Mini App events | Event | When it fires | | ---------------------- | ---------------------------------------------------------------------------------- | | `web_app_new_init` | The user opened the bot's mini app for the first time | | `web_app_init` | The user opened the mini app again (already opened it before) | | `web_app_anon_init` | The mini app was opened anonymously, without a Telegram user ID | | `new_user_webapp` | A new user confirmed data access (`write_access_allowed`) inside the mini app | | `write_access_allowed` | The user allowed the bot to send messages (requested from the mini app or the bot) | ## Incoming messages and content Any message received from a user creates an event. If the message text matches a configured [command](/en/app/actions.md) or [target](/en/api/send-event.md), the matching event is created instead of the generic one. | Event | When it fires | | ---------------- | --------------------------------------------------------------------------------------------------------------- | | `message` | A text message was received | | `photo` | A photo was received | | `video` | A video was received | | `audio` | An audio file was received | | `document` | A document/file was received | | `voice` | A voice message was received | | `video_note` | A video note (round video) was received | | `animation` | An animation/GIF was received | | `sticker` | A sticker was received | | `poll` | A poll was received | | `location` | A location was received | | `contact` | A contact was received | | `edited_message` | The user edited a previously sent message | | `/` | A command other than `/start` was invoked — the command name is substituted dynamically (e.g. `/help`, `/menu`) | ## Buttons and inline mode | Event | When it fires | | ------------------------------ | ----------------------------------------------------------------------------------- | | button text (dynamic) | An inline button with short text was tapped — the event name equals the button text | | `callback_query` | An inline button without text, or with long text, was tapped | | `InlineQuery` | The user used the bot's inline mode (`@botusername query`) | | `chosen_inline_result` | The user picked one of the inline search results | | mini app button text (dynamic) | The mini app sent data via `web_app_data` | ## Payments | Event | When it fires | | -------------------- | ---------------------------------------------------------------- | | `pre_checkout_query` | The user initiated a payment (confirmation step before charging) | | `successful_payment` | A payment was completed successfully | | `refunded_payment` | A payment was refunded | | `shipping_query` | The user selected a shipping option during checkout | ## Reactions and other actions | Event | When it fires | | -------------------------------- | --------------------------------------------------------- | | emoji (dynamic), e.g. `👍`, `❤️` | The user reacted to a bot message | | `custom_emoji` | The user added a custom emoji reaction | | `business_connect` | A Telegram business account was connected to the bot | | `business_disconnect` | A Telegram business account was disconnected from the bot | ## Outgoing messages from the bot Created on every successful message sent by the bot (failed sends don't create an event). | Event | When it fires | | ---------------- | ----------------------------- | | `sendmessage` | The bot sent a text message | | `sendphoto` | The bot sent a photo | | `sendvideo` | The bot sent a video | | `sendaudio` | The bot sent an audio file | | `senddocument` | The bot sent a document | | `sendvoice` | The bot sent a voice message | | `sendvideonote` | The bot sent a video note | | `sendanimation` | The bot sent an animation/GIF | | `sendsticker` | The bot sent a sticker | | `sendinvoice` | The bot sent an invoice | | `sendlocation` | The bot sent a location | | `sendmediagroup` | The bot sent a media group | | `forwardmessage` | The bot forwarded a message | ## Broadcasts | Event | When it fires | | ----------------- | ------------------------------------------------------------- | | `gs_mailing_send` | A broadcast message was successfully delivered to a recipient | ## Referral program | Event | When it fires | | ----------------- | -------------------------------------------------------- | | `referral_signup` | A new user signed up via a referral link/code | | `referral_reward` | The referrer was credited a reward for the referred user | | `referral_payout` | The referrer was paid out from the referral program | ## Automation (workflow) These events are created by the automation engine itself, regardless of what a specific chain is configured to do. They let you build reports on how your automations perform — how many users entered a chain, where they tend to drop off, how often errors happen. | Event | When it fires | | ------------------ | ------------------------------------------------------------------------------------------------ | | `workflow_started` | The automation's trigger matched, and a new run of the chain started for the user | | `node_executed` | An automation step (a condition or an action, but not the trigger itself) completed successfully | | `workflow_failed` | An automation step failed and the chain stopped | Automations can also create events in other ways: | Event | When it fires | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | arbitrary name (dynamic) | A workflow automation ran a "Create event" action — the event's name and value are set in the action's configuration and can reference workflow data | | arbitrary name (dynamic) | An event was sent via [the `/v1/send-event` API](/en/api/send-events.md) — the name is whatever the sender specifies | > Target events (goal/conversion completions) and events from custom commands you configure ("fake commands") also end up in the same events table, but their name and meaning depend on what you set up in your dashboard — so there's no single fixed list for them.