Telegram getUpdates と setWebhook の競合を安全に切り替える Runbook

Telegram Bot API の受信には基本ルールがあります。同じボットで getUpdates のポーリングと setWebhook のプッシュ配信を同時に使うことはできません。デプロイ後にメッセージが届かない場合は、まず現在どちらの受信経路が有効かを確認し、webhook を削除してポーリングに戻すのか、ポーリング worker を止めて webhook に移るのかを決めます。LINE も含む複数チャネルのサポート導線を作る場合は、この Bot API の問題と統合 inbox の問題を分けて考えるのが安全です。

要点

• getUpdates と setWebhook は Telegram 公式の Bot API 受信方式で、並行運用するものではありません。
• 変更前に getWebhookInfo を呼び出し、webhook URL が残っているか確認します。
• ポーリングに戻す場合は deleteWebhook を呼び、drop_pending_updates を本当に捨ててよいか判断します。
• 受信方式をまだ選んでいる段階なら、Telegram Bot API webhook vs unified inbound webhook を先に読むと整理できます。
• 認証情報の混同なら、Telegram API ID/API hash と bot token の違い が先です。

公式ドキュメント上の境界

Telegram の Bot API ドキュメントは、updates の受信方法を 2 つに分けています。getUpdates はアプリ側から Telegram をロングポーリングする方式で、webhook は Telegram からあなたの HTTPS URL にリクエストが届く方式です。同じページでは、outgoing webhook が設定されている間は getUpdates で updates を受け取れないこと、ポーリングに戻す場合は deleteWebhook を使うことも説明されています。

症状	あり得る状態	最初の確認
ポーリングで何も返らない	webhook URL が残っている	getWebhookInfo
webhook にリクエストが来ない	古い polling worker が残っている、または webhook 設定が不完全	worker を止めて確認
社内キューで重複や抜けがある	複数インスタンスが同じ処理を担当	owner を 1 つにする
切り替え後に古いテスト更新が流れる	pending updates が保持されている	処理するか捨てるか決める

Step 1: 現在の受信経路を確認する

BOT_TOKEN は環境変数に置き、ログに出さない前提で実行します。

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

レスポンスの url が空でなければ、そのボットにはまだ webhook が設定されています。url が空なら Bot API webhook は無効で、getUpdates を受信経路として使えます。

Step 2: webhook から getUpdates に戻す

まず webhook を削除します。

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

本番の問い合わせメッセージでは通常 false を選び、1 つの polling worker で冪等に処理します。true は、pending updates がテストデータである、またはプロダクトとして完全に切り直す判断をした場合だけにします。

その後、polling worker を 1 つだけ起動し、各 getUpdates レスポンスの後に offset を進めます。

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

Step 3: getUpdates から setWebhook に移す

先に polling worker を止めます。その後、本番サービスが所有する URL を設定します。

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

受信エンドポイントはすばやく応答し、Telegram update を保存してから CRM、AI 分類、担当者割り当てを非同期で動かします。この「保存してからルーティングする」考え方は webhook-first inbound integration checklist と同じです。ただし Telegram Bot API の Update と UnifyPort の event schema は別物です。

統合 inbound webhook を選ぶ場面

この runbook は Telegram bot の受信切り替えを直すためのものです。bot を通常の Telegram アカウント inbox に変えるものではなく、WhatsApp、LINE、TikTok、Zalo、X の形式を自動で統合するものでもありません。

チームが LINE と Telegram、WhatsApp などを 1 つのサポートキューに入れたいなら、UnifyPort webhook を作る方が自然です。詳細は Create webhook endpoint です。HTTPS url、status: "active"、message.received または ["*"] の購読、必要に応じた signing_secret を設定します。

{
  "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" }
  }
}

顧客が bot と会話すべき製品なら公式 Bot API を使います。既存アカウントや複数チャネルの inbound queue が目的なら、UnifyPort の非公式インターフェースが適しています。

FAQ

getUpdates と setWebhook は同時に使えますか？

いいえ。Telegram はこの 2 つを Bot API bot の相互排他的な受信方法として扱っています。ポーリング前に webhook を削除し、webhook 設定前に polling worker を止めます。

drop_pending_updates は true にすべきですか？

捨ててよい更新だけなら true にします。本番サポートメッセージは保存し、冪等に処理する方が安全です。

これは Telegram の通常アカウント接続ですか？

違います。Bot API は bot token を使います。UnifyPort で Telegram アカウントを接続すると、標準化された message.received event が届きます。

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