Skip to main content

Move Telegram webhooks to channel authentication

During the channel-authentication cutover, each bot's webhook moves from the previous API route to the API's channel-authentication webhook. From then on, the API records verified contact and bot permission and applies them to the account before acknowledging each update.

Do this inside the planned cutover window, together with the Mini App and API release.

Prerequisites​

  • The API release with channel authentication is deployed at its public HTTPS origin, for example https://api.example.com, and GET /.well-known/openid-configuration answers 200.
  • CHANNEL_AUTH_TELEGRAM_APPS_JSON holds each bot's token and a new random webhookSecret of 32 to 256 letters, digits, _ or -.

Set each webhook​

Run this once per bot, with that bot's token, its app identifier from CHANNEL_AUTH_TELEGRAM_APPS_JSON (such as client), and the same webhookSecret. Run it from a trusted shell; the command line contains the bot token.

curl -sS "https://api.telegram.org/bot<bot-token>/setWebhook" \
  -H "content-type: application/json" \
  -d '{"url":"https://api.example.com/webhooks/telegram/client","secret_token":"<webhook-secret>","allowed_updates":["message","my_chat_member"]}'

Expected result: {"ok":true,"result":true,"description":"Webhook was set"}.

Setting a new webhook URL stops Telegram from sending updates to the previous URL. Updates Telegram has not delivered yet go to the new URL; leave drop_pending_updates unset so none are lost.

Confirm delivery​

  1. Check the webhook's state:

    curl -sS "https://api.telegram.org/bot<bot-token>/getWebhookInfo"

    Expected result: url is the new URL, pending_update_count stays near 0, and there is no recent last_error_message. A 401 error there means the secret in CHANNEL_AUTH_TELEGRAM_APPS_JSON and secret_token differ. A 500 error means updates could not be applied; see Troubleshoot contact onboarding.

  2. From a test Telegram account, open the client Mini App, sign in, and share your contact with the bot.

  3. Expected result: the Mini App's onboarding status changes from contact_required to ready on its next status check.

Roll back​

Pointing a bot back at the previous route works only together with redeploying the previous API release, which still had /client/bot/updates. Before any client depends on Supabase sessions, you can do that with the same setWebhook call and the previous secret. After the cutover, prefer fixing forward: facts recorded by channel authentication are not copied back to the old flow, and accounts created after the cutover are unknown to the old release; see the cutover runbook.