Telegram getUpdates and setWebhook Conflict: A Safe Switching Runbook

Telegram Bot API update delivery has one core rule: getUpdates polling and setWebhook push delivery are mutually exclusive for the same bot. If a bot stops receiving messages after a deployment, first check which receiver is active, then either remove the webhook before polling or stop the polling worker before setting a webhook. Telegram’s official Bot API also says pending updates are stored only temporarily, so do the switch deliberately.

Key takeaways

• getUpdates and setWebhook are two official Bot API delivery modes, not layers you run in parallel.
• Use getWebhookInfo before changing anything; it tells you whether a webhook URL is currently set.
• If you switch back to polling, call deleteWebhook and choose whether drop_pending_updates is safe for your business flow.
• If the real job is a team inbox or cross-channel queue, compare this Bot API runbook with the Telegram Bot API webhook vs unified inbound webhook decision guide.
• If the confusion is credentials rather than delivery mode, start with Telegram API ID and API hash vs bot token.

What Telegram officially says

Telegram documents two ways to receive Bot API updates: getUpdates, where your code long-polls Telegram, and webhooks, where Telegram sends HTTPS requests to your endpoint. The same official page states that you cannot receive updates with getUpdates while an outgoing webhook is configured, and deleteWebhook is the method to remove webhook integration if you switch back to polling.

That means most switching failures are not mysterious. They are usually one of these states:

Symptom	Likely state	Safe next check
Polling returns nothing after a webhook test	A webhook URL is still set	Call getWebhookInfo
Webhook endpoint receives nothing after deployment	A polling worker is still the receiver you are operating around, or the webhook was not set correctly	Stop the worker, then inspect getWebhookInfo
Duplicate or missing internal processing	Two app instances are processing the same downstream queue	Pick one owner before retrying
A test flood appears after switching	Old pending updates were kept	Decide whether to process or drop pending updates

Step 1: inspect the current receiver

Run this from a controlled environment where BOT_TOKEN is an environment variable, not pasted into logs:

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

If the response contains a non-empty url, Telegram still has a webhook configured for that bot. If the URL is empty, the bot is not using a Bot API webhook, and getUpdates can be the active receiving path.

Do this before changing deployment flags. Guessing can lose pending work or create a confusing double migration.

Step 2: switch from webhook to getUpdates

If you are returning to polling, remove the webhook first:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook" \
  -d "drop_pending_updates=false"

Use drop_pending_updates=false when messages still matter and your worker can drain them idempotently. Use true only when the pending backlog is disposable test traffic or your product owner has explicitly chosen a clean cutover.

Then restart exactly one polling worker. In your app code, recalculate the offset after each getUpdates response so the same update is not processed repeatedly.

curl "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

Step 3: switch from getUpdates to setWebhook

If you are moving to push delivery, stop the polling worker first. Then set the webhook URL that your production service owns:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

Keep the receiving endpoint fast. Acknowledge the Telegram request promptly, store the update, and let slower CRM or AI work run after that. This mirrors the store-first pattern in the webhook-first inbound integration checklist, even though Telegram Bot API updates and UnifyPort events are different schemas.

When a unified inbound webhook is the better path

This runbook fixes a Telegram bot receiving problem. It does not turn the bot into an ordinary account inbox, and it does not normalize WhatsApp, LINE, TikTok, Zalo, or X.

If your support workflow needs a shared event layer, create a UnifyPort webhook endpoint instead. The deep reference is Create webhook endpoint: use an HTTPS url, set status: "active", subscribe to message.received or ["*"], and enable a signing_secret when you want X-Device-Signature verification.

A Telegram inbound event through UnifyPort uses the same standard envelope as other providers:

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z",
      "text": "Can you check my order?"
    },
    "event": { "kind": "message_received" }
  }
}

Use the official Bot API when the customer should talk to a bot identity and Telegram’s Update object is the right contract. Use the UnifyPort unofficial interface when the job is inbound intake from a connected messaging account or a multi-platform support queue.

FAQ

Can I use getUpdates and setWebhook at the same time?

No. Telegram documents them as mutually exclusive receiving methods for a Bot API bot. Remove the webhook before polling, or stop polling before setting the webhook.

Should I set drop_pending_updates to true?

Only when the pending backlog can be discarded. For production support messages, keep it false and drain updates with idempotent storage.

Is this the same as connecting a Telegram user account?

No. getUpdates and setWebhook belong to the Bot API and use a bot token. A connected Telegram account through UnifyPort uses the account authorization flow and emits normalized message.received events.

What should I open after this runbook?

For a bot-only product, continue with Telegram’s official Bot API docs. For a cross-channel inbox, open the UnifyPort webhook delivery and signature verification docs and create one signed receiver.

Sources checked on 2026-09-09

• Telegram Bot API getUpdates: https://core.telegram.org/bots/api#getupdates
• Telegram Bot API setWebhook: https://core.telegram.org/bots/api#setwebhook
• Telegram Bot API deleteWebhook: https://core.telegram.org/bots/api#deletewebhook
• Telegram webhook guide: https://core.telegram.org/bots/webhooks
• UnifyPort Create webhook endpoint
• UnifyPort Webhook delivery