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, triggers, automation, the mini app, or targets/conversions. Those are not listed here, since they are unique to each product.

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.

---

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_<status>	The member's status changed to anything else (e.g. chat_member_administrator, chat_member_restricted) — <status> 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 or target, 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
/<command>	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 — 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.