Receive updates: webhooks or getUpdates
What it is
Every event for your bot, from a message to a payment, arrives as an update. You get updates one of two ways, never both: your code pulls them with getUpdates (long polling), or Telegram posts each one to your HTTPS address (a webhook). Undelivered updates wait at most 24 hours.
How to do it
- Polling: call
getUpdatesin a loop with a positivetimeout, passingoffset= lastupdate_id+ 1 to confirm handled updates. - Webhook: call
setWebhookwith your HTTPSurland asecret_token; reject requests without a matchingX-Telegram-Bot-Api-Secret-Tokenheader. - Filter with
allowed_updates; setmax_connections(1–100, default 40) to your server's capacity. - Answer webhook requests with HTTP 2XX, or Telegram retries and eventually gives up.
- Check delivery with
getWebhookInfo:pending_update_count,last_error_message. - Back to polling:
deleteWebhook(drop_pending_updatesclears the queue).
Watch out
getUpdatesdoesn't work while a webhook is set.- Webhooks need port 443, 80, 88 or 8443, TLS 1.2 or higher, IPv4, and a certificate whose CN matches your domain; upload a self-signed one as
certificate. Requests come from 149.154.160.0/20 and 91.108.4.0/22. - An empty
allowed_updatesstill skipschat_member,message_reactionandmessage_reaction_count. - After a week without updates, the next
update_idis random. - Popular bots (about 300 requests a minute) get @BotFather status alerts when replies drop, by default at most one per hour.
- A local Bot API server allows any webhook port, plain HTTP and up to 100,000 connections.
With Gem
Gem doesn't host your bot's code or take its webhooks, and a creator's own bot isn't available yet. Projects run on @gembot, which Gem holds: Stars payments for offers, join requests, channel posts and answers in groups.
Sources
- https://core.telegram.org/bots/api#getting-updates
- https://core.telegram.org/bots/webhooks
- https://core.telegram.org/bots/features#status-alerts