Telegram Webhook の返信：レスポンス本文と個別の sendMessage 呼び出しを比較
Telegram では、webhook に対する HTTP レスポンス内で sendMessage などの Bot API メソッドを呼び出せます。ただし公式仕様では、その呼び出しが成功したかを確認したり、結果を取得したりすることはできません。送信後のメッセージ ID や API エラーが必要なら、Bot API を別途呼び出してください。受信確認として 200 OK を返すことと、チャットへの返信成功は別の事象です。
要点
- HTTP の受信確認、API メソッドの結果、利用者の既読は区別します。
- レスポンス内のメソッド呼び出しはリクエストを減らせますが、結果を取得できません。
- メッセージ ID や送信記録に依存する処理には、個別の
sendMessage呼び出しが適しています。 - UnifyPort は webhook のレスポンス本文を破棄します。送信には別の API 呼び出しが必要です。
Telegram の webhook レスポンスでできること
Telegram Bot API の公式リファレンスでは、webhook へのレスポンスで application/json、application/x-www-form-urlencoded、multipart/form-data を使ってパラメーターを渡し、method で実行するメソッドを指定できます。
たとえば JSON レスポンスに method: sendMessage と、適切な chat_id、text を含めます。これは API メソッドの呼び出し形式であり、受信した Update の形式ではありません。レスポンス本文に任意の文字列を書けばチャットに送られる、という意味でもありません。
公式 FAQは、リクエスト数を減らせる一方、成功の確認や結果の取得はできないと説明しています。サーバーログに HTTP レスポンスの成功が記録されても、欠けている送信結果を補うことはできません。
本記事は、すでにボットの更新を受信できていることを前提とします。受信するアカウントの種類や方式を選ぶ段階なら、Telegram Bot API webhook と統一受信 webhook の比較を参照してください。ポーリングか webhook かという選択と、受信後にどう返信するかは別の問題です。
レスポンス内の返信と個別 sendMessage 呼び出し
| 判断項目 | webhook レスポンス内で呼び出す | Bot API を別途呼び出す |
|---|---|---|
| 呼び出し形式 | 本文に method とパラメーターを含める | アプリから個別にメソッドを呼び出す |
| メソッドの結果 | 取得できない | Bot API の JSON を確認できる |
| 送信したメッセージ ID | この仕組みでは取得できない | sendMessage 成功時に Message が返る |
| エラー処理 | 結果に基づく分岐ができない | 返された ok、description、error_code を確認する |
| 向いている処理 | 結果が不要な簡単な返信 | 送信記録、ワーカー処理、後続アクション |
公式のレスポンス形式と sendMessage の定義では、レスポンスに ok が含まれ、成功時は result、失敗時はエラー情報が返ります。sendMessage は成功時に送信した Message を返します。
メソッドの成功は、利用者が読んだ証拠ではありません。また、個別の API 呼び出しでも、サーバー側で処理した後にクライアントがレスポンスを受け取れなければ、結果は不確定になります。
**想定例：**ボットが簡単な案内を返すだけで、後続処理がそのメッセージ ID を必要としないなら、レスポンス内の返信で足りる場合があります。送信した返信を問い合わせチケットに紐付けたり、API の拒否理由によって処理を変えたりするなら、個別に呼び出して実際の結果を保存します。
受信確認と送信結果を分離する
時間のかかる処理には、次のアプリケーション設計を推奨します。Telegram が追加で保証する API 動作ではありません。
- webhook の送信元を検証し、更新を永続ストレージに保存する。
- AI、CRM、送信処理を待たず、受信を確認する。
- ワーカーから Bot API を別途呼び出す。
- 実際の結果またはエラーをローカルのタスクに記録する。
- 通信タイムアウトを、確定した失敗ではなく「結果不明」として扱う。
ボットごとに更新を重複排除します。再配信時には既存タスクを参照し、別の返信を新規作成しないようにします。送信担当も一本化してください。同じ返信をレスポンスに埋め込み、さらにワーカーからも送信する設計は避けます。
Telegram は、webhook が 2XY 以外のステータスを返すなど、配信に失敗した場合に再試行すると説明しています。これは受信更新の配信を再試行する仕組みで、送信メソッドの結果管理を代替するものではありません。更新は届くのに返信が出ない場合は、設定変更より先に送信記録を確認します。getWebhookInfo の診断ガイドでは、配信状態だけでは業務処理の完了を証明できない理由を解説しています。
UnifyPort のレスポンス本文は送信命令にならない
UnifyPort の非公式インターフェースは、Telegram のレスポンス内メソッド呼び出しを採用していません。Webhook 配信リファレンスでは、任意の 2xx が配信確認となり、レスポンス本文は読み取った後に破棄されます。method: sendMessage を返しても、この仕様で送信が実行されることはありません。
接続済みのメッセージングアカウントでは、message.received を受信し、署名検証とイベント保存を行ってから確認を返します。signing_secret を設定した場合、X-Device-Signature は X-Device-Timestamp、ピリオド、未加工のリクエスト本文に対する HMAC-SHA256 です。
送信は X-Api-Key で認証した別の POST /v1/messages で行います。テキスト送信リファレンスは account_id、to.id、to.type、message.type、message.text を定義しています。レスポンス例の data.status: accepted を既読通知として扱わないでください。自動返信では data.message.direction も確認し、自分が送ったメッセージから返信ループが発生しないようにします。
LINE と Telegram を同じ受信処理にまとめる場合も、各プラットフォームの HTTP 応答仕様を混同しないことが重要です。ボットの身分が必要なら公式 Bot API を使います。UnifyPort のアカウント接続は別の連携方式であり、取得できなかった Bot API の結果を復元するものではありません。REST によるメッセージ履歴取得 API や再配信の保証もないため、必要なイベントは受信時に保存してください。
FAQ
sendMessage の JSON を返せば、個別の API 呼び出しは不要ですか？
Telegram Bot API webhook では、公式のメソッド応答形式を使えば可能です。ただし成功の確認や結果の取得はできません。
200 OK を返したら返信成功ですか？
いいえ。webhook の配信を確認しただけです。送信メソッドの結果とは別です。
個別 API 呼び出しのタイムアウト後は自動で再送すべきですか？
無条件に再送しないでください。リモート側で送信済みなのにレスポンスだけ失われた可能性があります。結果不明の状態を記録し、照合または再試行の方針に沿って判断します。
UnifyPort の webhook レスポンスに返信を書けますか？
本文は破棄されます。別途 POST /v1/messages を呼び出してください。
次のステップと出典
送信結果を確認する必要があるかで方式を選びましょう。接続済みアカウントの実装は、テキスト送信 API の仕様から確認できます。
公式情報の確認日：2026-09-20。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。