Triggers
Choose what your bot responds to: a word, command, button, payment, or website event.
Nesta página
A trigger answers “What must happen for the bot to run this reaction?” For example, someone types /help, presses a button, or pays an invoice.
You can enable several options in the editor's Trigger section. Any one is enough: the /help command or the word “help.” To respond only to certain people or in certain chats, add conditions.
Text message
Fires on a text message or a media caption. The "What to look for" field offers several modes:
- Keywords: a list of words or phrases. The "Match" parameter: contains, exact match, starts with, regular expression; plus a "Case-sensitive" checkbox. One trigger accepts up to 100 keywords of up to 200 characters each (see Platform limits). Use collections for larger lists.
- Link: the message contains a URL.
- Email: the message contains an email address.
- Mention (@username): the message contains a mention.
- Any text: any text message.
Command
Fires on slash commands. List command names (without the /) in the "Commands (without '/')" field, for example help, menu. The bot will respond to /help and /menu.
/start command
A link such as https://t.me/your_bot?start=promo starts the bot with an extra value, promo. You can use it to distinguish visitors from a promotion. Enter only promo in Start link tag, without the address or start=. Leave the field empty to respond to any /start.
Inline button press (callback)
Fires when someone presses a button under a message that sends an event to the bot. Its technical callback_data value can differ from the visible label. "Button data (callback_data)" sets the value to look for, and "Match" selects exact, starts with, contains, or regular expression. A link button only opens an address; it does not fire this trigger.
Media
Fires on attachments of selected types: Photo, Video, Video message, Document, Audio, Voice, GIF, Sticker, Dice, Game, Poll, Contact, Location, Venue, Album.
System event
Fires on chat events: Joined via link, Added to chat, Left chat, Removed from chat, Status changed, Join request, Reaction on message, Reaction counter. Useful for welcome messages, moderation, and join request handling.
For Telegram membership events, use {{system.subject_id}} and the other system event substitutions. The person affected can differ from the actor: {{user_id}} identifies the actor. If one message adds several members, each member produces a separate event.
There is also a platform event:
-
Label expired (
label_expired): a subscriber's temporary label has expired. The reaction can use{{event.label_name}},{{event.label_id}}, and{{event.expired_at}}.The label is not removed immediately. While the reaction runs, a “has label” condition can still see it. The label is removed only after successful processing. If the reaction fails, the label stays and the event is retried.
This event belongs to a subscriber, not a chat message, so
{{chat_id}}is empty. Send message delivers to the subscriber's private chat. Change permissions requires an explicit Chat (chat_id), such as a club chat. Without it, processing fails and is retried. Other actions that need the event chat and have no explicit destination do not run.
Reply and forwarded
- Reply to message: fires when the incoming message is a reply to another message.
- Forwarded message: fires on forwarded messages.
Every N-th message
Fires on every N-th message from a user (the "Every message #" field). Suitable for periodic hints or anti-flood measures.
Scheduled (dates)
Fires at specified points in time (a list of dates). A scheduled reaction is broadcast to active subscribers when the time arrives: see Broadcasts.
Payment
Fires when an invoice issued by the bot changes status. Set the Payment status (Paid, Failed, or Refunded), Payment provider, and Minimum amount, kopecks. See Payments and balance for the “payment → access” flow.
Client or website event
Fires on a client or website event with the specified name. The platform records referral.joined when a new subscriber joins through ?start=ref_<user_id>. The event has referrer_tg_user_id (the referrer's ID), referrals_count (their current total of invited subscribers), and start_payload (the new subscriber's start-link tag).
This reaction runs as the new subscriber, so an ordinary Send message action sends to that person. You can use {{ctx.referrer_id}} and {{event.referrer_tg_user_id}} in fields that support substitutions, but they do not change the recipient on their own. The send_message action has no dynamic recipient field. {{ctx.referrer_id}} is also available in the new subscriber's first /start reaction.
Incoming web request (webhook)
Fires on an HTTP request from an external source. Enable this trigger and save the reaction. The Address field then shows the generated webhook URL for this reaction. You can copy the address but cannot edit it. Set a Secret token to protect the endpoint and choose a Method (POST / GET / PUT / ANY). Request data enters the execution context and is available to actions as {{ctx.field}}. See Web requests and webhooks.
What's next
- Conditions and chats: narrow the trigger by audience and location.
- Actions: what the bot does in response.