Receiving updates

Not implemented

Neither transport exists yet — getUpdates and setWebhook both return 404, and no bot token can be issued. See implementation status.

A bot never opens a connection to a person — it reacts to updates. There are two ways to receive them and a bot uses exactly one at a time: registering a webhook disables polling, and deleting the webhook re-enables it.

Long polling

Call getUpdates in a loop. Each call blocks until something arrives or timeout seconds pass, so an idle bot costs one open request rather than a busy loop.

GET /bot<TOKEN>/getUpdates?offset=<id>&limit=100&timeout=50

Pass offset as the last update_id you handled plus one. That acknowledges everything below it; the server drops those and never sends them again. Forgetting the increment is the classic bug — the same update arrives forever.

Only one getUpdates may be open per token. A second concurrent call fails with 409 Conflict, which in practice means you deployed twice without stopping the old process.

Needs no public address, so it is the right choice for development and for anything behind NAT.

Webhooks

Register an HTTPS URL and each update is POSTed to it as JSON.

POST /bot<TOKEN>/setWebhook
{"url": "https://example.com/hook", "secret_token": "..."}

HTTPS only, on port 443, 80, 88 or 8443. Set secret_token and check the X-Grom-Bot-Api-Secret-Token header on every request — without it anyone who learns your URL can forge updates.

Delivery is at-least-once, retried with backoff at 1s, 5s, 30s, 2m and 10m, then dropped after 24 hours. Your handler will occasionally see the same update_id twice, so make it idempotent: store handled ids, or make the side effect naturally repeatable.

Return 200 quickly. The retry schedule keys off your response, so slow handlers turn one update into several deliveries. Acknowledge first, work afterwards.

getWebhookInfo reports pending_update_count and the last delivery error — the first thing to check when a bot goes quiet.

Ordering and delivery

Updates are FIFO per bot and update_id increases monotonically. Ordering is not guaranteed across bots, and with a webhook your own concurrency can reorder handling even though delivery was ordered — if order matters, serialise on chat_id in your handler.

Update types

Pass any subset as allowed_updates to getUpdates or setWebhook. An empty list means every type except those that must be requested explicitly.

Type	Fires when
message	A new message in a private chat, group or supergroup the bot is in.
edited_message	A message the bot can see was edited.
channel_post	A new post in a channel the bot administers.
edited_channel_post	A channel post was edited.
business_connection	The bot was connected to or disconnected from a business account.
business_message	A new message in a chat managed through a connected business account.
edited_business_message	A business-account message was edited.
deleted_business_messages	Messages were deleted from a connected business account.
message_reaction	A reaction changed on a message. Must be requested explicitly in allowed_updates.
message_reaction_count	Anonymous reaction totals changed on a channel post. Must be requested explicitly.
inline_query	Someone typed the bot's username in any chat's composer.
chosen_inline_result	An inline result the bot offered was picked. Requires inline feedback to be enabled.
callback_query	An inline keyboard button was pressed.
shipping_query	A shipping address was submitted for an invoice with flexible pricing.
pre_checkout_query	A payment is about to be charged and needs the bot's confirmation.
poll	The state of a poll the bot sent changed.
poll_answer	A user voted in a non-anonymous poll the bot sent.
my_chat_member	The bot's own membership or rights changed — added, removed, promoted, demoted.
chat_member	Another member's status changed. Must be requested explicitly in allowed_updates.
chat_join_request	Someone requested to join a chat where the bot can approve requests.
chat_boost	A chat was boosted.
removed_chat_boost	A boost was removed from a chat.
purchased_paid_media	A user bought paid media the bot sent.