Prerequisites
The connector should already be set up, with a Connector Profile and a Linked Account. See Getting Started on the Telegram connector page.How StackOne manages the webhook
StackOne creates and manages the Telegram webhook automatically using the bot’s token. When events are enabled on the linked account, StackOne calls setWebhook with the events you selected, and it removes the webhook when the account is disconnected. No webhook setup is needed in Telegram.
- Only the events selected in StackOne are delivered. Changing the selection re-registers the webhook with the new event list.
- The webhook covers every chat the bot is a member of.
- The linked account’s Native Webhook URL field shows the URL StackOne registers with Telegram. You don’t need to copy it anywhere.
- Some events are only sent when the bot has certain features or permissions turned on. The sections below show how to turn them on.
Turn on bot features for optional events
Inline queries, guest messages and managed bots are off by default. Turn them on in the BotFather Mini App only if you want those events.
Open the BotFather Mini App
In Telegram, open the chat with BotFather and click Open next to the message field.
- If Telegram asks to launch the web app, confirm it.
Select your bot
Under My bots, click the bot connected to StackOne.
Open Bot Settings
On the bot’s page, click Bot Settings in the Settings list.
- The bot token shown at the top of this page grants full control of the bot. Don’t share it.
Turn on the modes the events need
Under Mode Settings, turn on only the modes for the events you plan to use.
- Inline Mode — required for
inline_queryandchosen_inline_result. Open it and turn inline mode on. - Bot Management Mode — required for
managed_bot. - Guest Chat Mode — required for
guest_message.
Check the group settings
Scroll to Groups and Channels. Keep Allow Groups on so the bot can be added to groups.
- With Group Privacy on, the bot only receives group messages that mention it, reply to it or contain a command. Turn it off to receive every group message as a
messageevent.
Make the bot a chat administrator
Telegram only sends reaction, member, boost and channel events for chats where the bot is an administrator.
- Needs admin in the chat:
message_reaction,message_reaction_count,chat_member,chat_boost,removed_chat_boost,channel_postandedited_channel_post - Needs the invite users right:
chat_join_request
Open the group's administrators
Open the group, click its name at the top, then click the pencil icon to edit the group.
- Click Administrators.
- Click the add-admin button in the bottom corner and select your bot.
Grant the admin rights
Under What can this admin do?, keep the default rights on and confirm with the check mark at the top.
- Keep Ban Users on to receive
chat_memberupdates when members are restricted or removed. - Keep Invite Users via Link on to receive
chat_join_requestevents.
Add the bot to a channel
Telegram Web can’t add a bot to a channel. Use the Telegram mobile or desktop app instead.
- Open the channel, tap its name, then tap Edit.
- Tap Administrators, then Add Admin, and select your bot.
Available webhook events
The following Telegram updates can be enabled as events. Only events selected in StackOne are included in the webhook, so Telegram won’t deliver the others.
Message events
Events for messages sent to the bot in private chats and groups.
- Message (
message) — Fired when the bot receives a new message of any kind, such as text, a photo or a document - Edited Message (
edited_message) — Fired when a message known to the bot is edited - Guest Message (
guest_message) — Fired when someone mentions the bot in a chat it isn’t a member of (Guest Chat Mode) - Stopped Message Generation (
stopped_message_generation) — Fired when a user taps Stop on a draft the bot is streaming
Channel events
Events for channels where the bot is an administrator.
- Channel Post (
channel_post) — Fired when a new post is published in the channel - Edited Channel Post (
edited_channel_post) — Fired when a channel post is edited
Interaction events
Events from buttons and inline mode.
- Callback Query (
callback_query) — Fired when a user presses an inline keyboard button on one of the bot’s messages - Inline Query (
inline_query) — Fired when a user types @botname followed by a query in any chat (Inline Mode) - Chosen Inline Result (
chosen_inline_result) — Fired when a user picks one of the bot’s inline results and sends it
Reaction events
Events for reactions in chats where the bot is an administrator.
- Message Reaction (
message_reaction) — Fired when a user changes their reaction to a message - Message Reaction Count (
message_reaction_count) — Fired when anonymous reaction counts on a message change
Poll events
Events for polls.
- Poll (
poll) — Fired when a poll sent by the bot, or a poll that is manually stopped, changes state - Poll Answer (
poll_answer) — Fired when a user votes or changes their vote in a non-anonymous poll sent by the bot
Member events
Events for chat membership.
- My Chat Member (
my_chat_member) — Fired when the bot’s own status changes, for example when it is added to a group, promoted, or blocked by a user - Chat Member (
chat_member) — Fired when another member joins, leaves or is promoted, restricted or banned in a chat where the bot is an administrator - Chat Join Request (
chat_join_request) — Fired when a user asks to join a chat through a join-request invite link
Boost events
Events for chat boosts in chats where the bot is an administrator.
- Chat Boost (
chat_boost) — Fired when a boost is added or changed - Removed Chat Boost (
removed_chat_boost) — Fired when a boost is removed
Payment events
Events for invoices, paid media and subscriptions sent by the bot.
- Shipping Query (
shipping_query) — Fired when a user enters a shipping address for a flexible-price invoice - Pre-Checkout Query (
pre_checkout_query) — Fired when a user confirms a payment. The bot must approve it within 10 seconds or Telegram cancels the payment - Purchased Paid Media (
purchased_paid_media) — Fired when a user buys paid media the bot sent - Subscription (
subscription) — Fired when a user’s paid subscription to the bot changes
Telegram Business events
Events for Telegram Business accounts connected to the bot.
- Business Connection (
business_connection) — Fired when the bot is connected to or disconnected from a business account - Business Message (
business_message) — Fired when a connected business account receives a new message - Edited Business Message (
edited_business_message) — Fired when a message in a connected business account is edited - Deleted Business Messages (
deleted_business_messages) — Fired when messages are deleted from a connected business account
Managed bot events
Events for bots created and managed by this bot.
- Managed Bot (
managed_bot) — Fired when a new bot is created to be managed by this bot, or a managed bot’s token or owner changes (Bot Management Mode)
Delivery format
Details of how Telegram delivers events to StackOne.
Check the payload format
Each delivery is an HTTP POST with one Telegram Update. It contains update_id and exactly one update-type field, such as message or callback_query. StackOne identifies the event by which field is present and uses update_id as the event ID.
Verify the secret token
StackOne registers a secret token with the webhook. Telegram sends it on every delivery in the X-Telegram-Bot-Api-Secret-Token header.
Handle retries and delays
Telegram retries deliveries that don’t receive a 2xx response.
- Message Reaction Count updates are grouped by Telegram and can arrive a few minutes late.