TelegramボットのWebhook設定：開発者向け完全ガイド

TelegramボットのWebhook設定は、サーバーをTelegramの更新ストリームに接続し、メッセージがポーリングループではなくリアルタイムで到着するようにします。 Bot API を使用してカスタムボットを構築している場合、Webhookは標準的な本番パスです。Telegramは各更新をHTTPSエンドポイントにPOSTし、コードが応答します。

このガイドでは、前提条件、登録、動作するハンドラーの例、検証、トラブルシューティング、および自己ホスティングよりも TeleClaw のようなマネージドプラットフォームがより理にかなっている場合について説明します。

主なポイント

• Webhookとロングポーリングは相互に排他的です。 Webhookを設定すると、削除するまで getUpdates が無効になります。
• HTTPSは必須です。 エンドポイントにはTLS 1.2以上、一致する証明書、およびポート443、80、88、または8443が必要です。
• setWebhook で登録し、getWebhookInfo で検証します。 更新が流れなくなった場合は last_error_message を確認してください。
• secret_token を使用して、リクエストがURLをヒットするランダムなスキャナーではなく、Telegramからのものであることを確認します。
• ノーコードの代替手段： TeleClaw はホスティングと配信を処理するため、サーバーレイヤーを完全にスキップできます。

Webhook vs ロングポーリング：どちらを選択するか

Telegramは更新を受信する2つの方法を提供しています。 Bots FAQ によると、ボットごとに1つの方法を選択します。両方を同時に実行することはできません。

ロングポーリングはプロトタイプを最も速く作成する方法です。ボットはループ内で getUpdates を呼び出し、各バッチを処理し、オフセットを進めます。ドメインも証明書もオープンポートも必要ありません。

Webhookはモデルを反転させます。誰かがボットにメッセージを送るたびに、TelegramはHTTPS POSTをURLに送信します。これにより、アイドル状態のポーリングリクエストが削除され、反応時間が短縮されます。これは、サポートボット、支払いフロー、大規模なグループモデレーションにとって重要です。

まだボット自体を登録していない場合は、BotFatherからトークンを取得するために、まず Telegramボットの作成ガイド から始めてください。

TelegramボットのWebhook設定の前提条件

setWebhook を呼び出す前に、インフラストラクチャが 公式Webhookガイド のTelegramの要件を満たしていることを確認してください。

• @BotFather からのボットトークン（上記のボット作成ガイドを参照）。
• 有効なTLS証明書を持つ公開ドメイン。自己署名証明書は、certificate パラメータを介して公開鍵をアップロードした場合にのみ機能します。
• サーバー上のサポートされているポート：443（デフォルト）、80、88、または8443。他のポートは拒否されます。
• 証明書のCNまたはSANは、Webhook URLのドメインと一致する必要があります。ワイルドカード証明書は機能しない場合があります。リダイレクトはサポートされていません。
• Telegramサブネット 149.154.160.0/20 および 91.108.4.0/22 からのインバウンドPOSTアクセス。

ローカル開発の場合、localhostをトンネル（ngrok、Cloudflare Tunnelなど）を介して公開し、公開HTTPS URLを取得します。Webhookを登録する前に、トンネルがPOSTリクエストに対してHTTP 200を返すことをテストしてください。

ステップ1：Webhookエンドポイントを構築する

サーバーには、POSTリクエストを受け入れ、JSON Update オブジェクトを解析し、HTTP 200を迅速に返すルートが必要です。ハンドラーが遅いと、Telegramは再試行し、最終的に getWebhookInfo でエラーを報告します。

Expressを使用した最小限のNode.jsの例：

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // update.message, update.callback_queryなどを処理します。
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Flaskを使用したPythonも同じパターンに従います。request からJSONを読み取り、設定されている場合はシークレットヘッダーを検証し、更新を処理し、200を返します。

迅速に応答します。 重い処理（データベースへの書き込み、AI API呼び出し）はバックグラウンドキューに送るべきです。Telegramは迅速な確認を期待しています。 Bot API webhook notes に記載されているように、個別のAPI呼び出しを行う代わりに、method フィールドを持つJSONボディを返すことでインラインで返信することもできます。

ステップ2：setWebhookでTelegramボットのWebhookを設定する

エンドポイントが稼働したら、Bot APIに登録します。<TOKEN> とURLを自分の値に置き換えてください。

curlを使用する場合：

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

パラメータリファレンス：

• url (必須)：HTTPSエンドポイント。Webhookを削除するには空の文字列を使用します。
• secret_token (オプション)：1〜256文字（A-Z、a-z、0-9、_、-）。Telegramは X-Telegram-Bot-Api-Secret-Token ヘッダーで送信します。
• max_connections (オプション)：1〜100の同時接続。デフォルトは40です。
• allowed_updates (オプション)：受信する更新の種類を制限します。メッセージのみを処理する場合、ペイロードサイズを削減します。
• drop_pending_updates (オプション)：Webhookを切り替えるときにキューに入っている更新を破棄するには true に設定します。
• certificate (オプション)：自己署名証明書の場合、公開鍵ファイルをアップロードします。

成功した応答は {"ok":true,"result":true,"description":"Webhook was set"} のようになります。

ステップ3：getWebhookInfoで検証する

登録は常にすぐに確認してください。これは、更新が届かなくなった場合の最初のトラブルシューティングツールです。

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

応答例：

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

これらのフィールドに注目してください。

• url: 空の場合、Webhookはアクティブではありません（ボットはロングポーリングを使用しています）。
• pending_update_count: 配信を待っているキューに入っている更新。数が増加している場合は配信失敗を示します。
• last_error_date および last_error_message: 最新の失敗理由。根本原因を修正すると、Telegramは自動的に再試行します。
• ip_address: 現在エンドポイントをヒットしているTelegram IP。

実際のTelegramアカウントからボットにテストメッセージを送信します。pending_update_count がゼロのままで、サーバーログにPOSTが表示される場合、TelegramボットのWebhook設定は機能しています。

TelegramボットのWebhook例：参加リクエストハンドラー

参加リクエストボット（Guardianスタイルの承認フロー）には、chat_join_request 更新タイプが必要です。 Guardianボットガイド では、製品側の側面について説明しています。ここではWebhookの配線について説明します。

参加リクエストを有効にして登録します。

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

ハンドラーロジック（擬似コード）：

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // スクリーニングロジックを実行し、Bot APIを介して承認または拒否します。
 await approveChatJoinRequest(chat.id, from.id);
}

Telegramは参加リクエストをプッシュ更新として配信するため、Webhookは、リクエストの期限が切れる前に応答する必要がある承認ボットに自然に適合します。

TelegramボットのWebhookを削除し、ポーリングに戻す

getUpdates を使用してローカルでデバッグする必要がありますか？まずWebhookを削除してください。

deleteWebhook を使用したオプションA：

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

setWebhook と空のURLを使用したオプションB：

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

どちらの方法もロングポーリングを再度有効にします。この手順をスキップすると、Webhookがまだ本番URLに登録されているため、getUpdates は何も返しません。

一般的なWebhookエラーのトラブルシューティング

getWebhookInfo がエラーを表示する場合、メッセージを修正に合わせます。

本番環境では、getWebhookInfo を定期的に実行してください。last_error_message を早期に検出することで、何時間ものサイレントメッセージ損失を防ぐことができます。

サーバーをスキップ：TeleClawによるマネージドボット

すべてのボットにカスタムWebhookインフラストラクチャが必要なわけではありません。グループまたはビジネスチャネル向けのAIアシスタントが目標である場合、ホスティングと更新の配信は解決済みの問題です。

TeleClaw は、BotFatherトークンをOpenClawを搭載したマネージドランタイムに接続します。ダッシュボードでパーソナリティ、ナレッジベース、モデレーションルールを設定します。プラットフォームはHTTPSエンドポイント、スケーリング、AIモデルルーティングを処理します。グループ管理者に @claw を追加するだけで、Webhookハンドラーを記述することなく稼働できます。

TeleClawの機能ページ で、マネージドボットができることを探ってみましょう。完全なノーコードウォークスルーについては、 Telegramチャットボットのノーコードガイド を参照してください。

独自のバックエンド、規制されたデータレジデンシー、または非標準の更新処理など、完全な制御が必要な場合は、カスタムWebhookが依然として理にかなっています。それ以外の場合、証明書管理、監視、再試行処理の運用コストは急速に増加します。

結論

TelegramボットのWebhook設定は、HTTPSエンドポイントのデプロイ、setWebhook の呼び出し、getWebhookInfo での検証、およびエラーの監視という4つのステップに集約されます。リクエスト検証には secret_token を使用し、処理する allowed_updates を制限し、ハンドラーを高速に保ちます。

サーバーを実行せずに本番プッシュ配信を望む開発者は、代わりに TeleClaw を使用できます。トークンを貼り付け、AIの動作を設定し、更新がどのように到着するかではなく、ボットが何を言うかに集中してください。

Webhookを管理せずにAIボットを起動する準備はできましたか？ Telegramグループに@clawを追加 →