← 全記事
比較

Telegram Bot API Webhook と統合インバウンド Webhook：受信経路の選び方

Telegram Bot API のポーリング、Telegram setWebhook、統合インバウンド webhook を比べるなら、まず見るべきなのは「どのアカウントとして受信するのか」です。Telegram Bot API が受け取るのは bot token にひもづく Bot の updates です。通常の Telegram アカウントをそのままサポート受信箱にするものではありません。Bot が正しい窓口なら setWebhook で HTTPS push、または getUpdates で polling を使います。既存の Telegram アカウントで受けたい、または Telegram と LINE、WhatsApp、TikTok、Zalo、X を同じ受信キューに入れたいなら、UnifyPort の統合インバウンド webhook が合います。

要点

  • Telegram 公式 Bot API の token は Bot を認証するためのものです。Telegram の公式チュートリアルでも、@BotFather から得る token は Bot を認証するものだと説明されています。
  • Telegram 公式ドキュメントでは、Bot API updates の受信方式として getUpdates（pull）と setWebhook（push）が説明されています。どちらも Bot 向けの選択肢です。
  • UnifyPort の統合インバウンド webhook は別のレイヤーです。接続した messaging account から、署名付きの message.received イベントを同じ envelope で受け取ります。
  • 検索意図が telegram bot api authorizing your bot token に近い場合は、先に Telegram API ID / API hash と Bot Token の違い を確認すると整理しやすくなります。
  • 実装イメージを見たい場合は、Cursor で Telegram-to-Slack relay を作る記事 も参考になります。

Telegram 公式 Bot API が実際に受け取るもの

Telegram の公式 Bot API ドキュメントでは、Bot は固有の token で認可されると説明されています。Bot を作成すると token が発行され、その token を使って Bot API にリクエストします。公式チュートリアルはさらに明確で、その token はあなたのアカウントではなく Bot を認証するものです。

開発チームが「Telegram login API」や「authorizing your bot token」を検索するとき、実際には次の三つの仕事が混ざっていることがあります。

  1. Telegram Bot を作る。ユーザーは Bot に直接話しかけます。
  2. 通常の Telegram アカウントを接続する。そのアカウントが参加しているチャットからメッセージを受けます。
  3. クロスチャネルのサポートキューを作る。Telegram は LINE、WhatsApp、Zalo、TikTok、X と並ぶ一つの入口です。

Bot API は一つ目の仕事にはきれいに合います。しかし二つ目、三つ目とはアーキテクチャが違います。二つ目では Telegram core API の application credentials、つまり api_id と api_hash が関係します。UnifyPort の Telegram authorization docs では、それぞれ provider_data.api_id、provider_data.api_hash として扱い、code login では provider_data.phone も使います。

Telegram Bot API webhook vs getUpdates

Telegram の公式 webhook guide は、Bot updates の処理方法として getUpdates と setWebhook を説明しています。違いは次の通りです。

選択肢配信モデル向いているケース主な運用上の注意
getUpdates自分のコードが Telegram を pollingローカル試作、シンプルな Bot、低トラフィックpolling loop、offset、空レスポンスを自分で扱う
setWebhookTelegram が HTTPS POST を送る安定した公開 endpoint を持つ本番 Bot到達可能な HTTPS receiver と配信処理を運用する
UnifyPort 統合 webhookUnifyPort が標準化された署名付きイベントを送る既存 messaging account とクロスチャネル受信キューTelegram Update ではなく UnifyPort event contract に合わせる

Telegram だけの Bot なら、setWebhook は本番向けの選択肢になりやすいです。updates がサーバーに push されるからです。小さな社内ツールや試作なら getUpdates で始めるのも自然です。ただしどちらも Bot API モデル内の話であり、bot token、Telegram 固有の update JSON、Telegram 固有の受信処理が前提です。

Bot という身份が合わない場合

受信に使う身份は、顧客がすでに使っている連絡先と合っている必要があります。顧客がすでに特定の Telegram アカウントに連絡しているなら、新しい Bot に移ってもらうこと自体が摩擦になります。さらに日本やタイでは LINE が重要な窓口になることが多く、LINE と Telegram を別々の受信設計にすると、サポートチーム側の運用が分断されます。

ここで問うべきなのは、インバウンドサポートの source of truth は何かです。答えが「メッセージが到着した瞬間のイベント」なら、署名付きイベントストリームをキューの前段に置き、早い段階で正規化するのが自然です。

Telegram のネイティブ自動化が便利になっても、クロスチャネル受信キューの役割は残ります。この境界は Telegram chat automation と cross-channel inbound queue でも整理しています。

UnifyPort はどこに入るか

UnifyPort は各 provider のイベントを受け、統一された webhook envelope としてあなたの endpoint に届けます。詳細なフィールドは Standard event types and payload を参照してください。delivery headers、HMAC-SHA256 verification、retries は Webhook delivery and signature verification にまとまっています。

Telegram の inbound text message は、他の provider と同じトップレベル構造で届きます。

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

signing_secret を有効にしている場合、receiver は X-Device-Signature を検証します。署名計算には raw request body を使い、JSON を再シリアライズしてはいけません。配信は at-least-once なので、event id による冪等処理も必要です。receiver の作成には POST /v1/webhook-endpoints を使い、公開 HTTPS url、subscribed_events（例: ["message.received"] または ["*"]）、任意の signing_secret を設定します。

小規模チーム向けの判断基準

公式 Bot API を選ぶべきケース：

  • 顧客が Bot に話しかける設計で問題ない。
  • ワークフローが Telegram のみで完結する。
  • Telegram Update object をそのまま内部モデルにしたい。
  • setWebhook 用の公開 HTTPS endpoint がある、または getUpdates polling で十分。

UnifyPort 統合インバウンド webhook を選ぶべきケース：

  • 受信箱がすでに通常の Telegram アカウントにある。
  • Telegram と LINE、WhatsApp、TikTok、Zalo、X を同じキューに入れたい。
  • message.received、message.updated、receipts、reactions、account status を一つの schema で処理したい。
  • provider ごとの receiver 実装ではなく、同じ HMAC-SHA256 verification pattern を使いたい。

制限とトレードオフ

UnifyPort は Telegram Bot API のすべての機能を置き換えるものではありません。inline keyboards、bot commands、BotFather configuration、その他 Bot 専用機能がプロダクトの中心なら、公式 Bot API が適しています。公開 Telegram Bot を作るなら、bot token が正しい credential です。

統合 webhook が強いのは、inbound intake と routing です。安定した event contract は得られますが、イベント保存、retry の冪等処理、provider ごとの authorization 運用は引き続き必要です。

FAQ

Telegram bot token と Telegram API ID / API hash は同じですか？

違います。bot token は Bot API の Bot を認証します。api_id と api_hash は Telegram core API の application credentials です。ここが主な疑問なら、まず Telegram API ID / API hash と Bot Token の違い を読んでください。

Telegram Bot では getUpdates と setWebhook のどちらを使うべきですか？

シンプルな polling loop で始めたいなら getUpdates。安定した HTTPS endpoint があり、Telegram から push してほしいなら setWebhook。どちらも Bot 向けの公式 Bot API 方式です。

Telegram Bot API webhook は通常の Telegram アカウント宛のメッセージを受け取れますか？

いいえ。Bot API webhook が受け取るのは、bot token で識別される Bot の updates です。通常アカウントやクロスチャネル support queue には、UnifyPort の統合 webhook のような account-level inbound path を使います。

UnifyPort を選んだ後の最初のステップは？

アカウント接続の前に receiver を登録します。Create webhook endpoint には url、status、subscribed_events、signing_secret、retry_policy.max_attempts が載っています。

次のステップ

Bot-only の Telegram プロダクトなら、Telegram Bot API docs から進めてください。サポートや自動化キューを作るなら、UnifyPort の webhook events reference を開き、まず一つの message.received handler を実装してから LINE など他チャネルを追加します。

2026-08-28 に確認した情報源

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。

API Key を取得API リファレンスを見る