Telegramのインラインボタンが読み込み中のまま？answerCallbackQueryを確認

Telegramのインラインコールバックボタンが読み込み中のままになる場合、受信した callback_query に対してBotが answerCallbackQuery を呼び出しているか確認してください。WebhookでHTTP 200 を返すだけでは、この呼び出しの代わりになりません。Telegramは、通知文を表示しない場合もコールバックへの応答を求めています。操作には速やかに応答し、時間のかかる業務処理の結果は別に追跡します。

要点

• コールバックボタンが生成するのは通常のテキストメッセージではなく callback_query です。
• クエリの id を callback_query_id に渡します。メッセージ、チャット、更新のIDとは別物です。
• 通知文は任意なので、文字を表示せずに応答できます。
• 読み込み表示が消えても、決済や承認、サポート処理の完了を意味しません。

読み込み表示とanswerCallbackQueryの関係

Telegram Bot APIの公式リファレンスでは、コールバックボタンとURLボタンを区別しています。callback_data はコールバッククエリとしてBotに送られますが、URLボタンは設定されたリンクを開きます。まず作成したボタンの種類を確認しましょう。

コールバックを使う操作には、異なる三つの結果があります。

結果	確認できる根拠	それだけでは分からないこと
Webhook配信の受領確認	受信側の成功HTTPレスポンス	コールバックに応答したか
ボタン操作への応答	対象クエリへの answerCallbackQuery	業務処理が成功したか
業務処理の完了	アプリケーションが確定した結果	クリックの受信や応答だけでは判断できない

公式リファレンスによると、answerCallbackQuery は通知またはアラートを表示でき、成功時に True を返します。必須パラメーターは callback_query_id で、text は任意です。通常のWebhook受領確認では代用できません。

Bot APIメソッドをWebhookレスポンスの本文に含めるか、別リクエストにするかについては、Webhookレスポンスと個別APIリクエストの比較を参照してください。それは呼び出し方の選択であり、この記事の焦点はボタン操作への応答漏れです。

どこで止まっているかを切り分ける

ハンドラーにコールバックが届かない

通常のメッセージログだけでなく、受信した更新の種類を確認します。ディスパッチャーが callback_query を処理しているか、明示した allowed_updates に含まれているかを調べてください。Telegramでは allowed_updates を省略すると以前の設定が使われます。後の設定リクエストで省略しても、フィルターのリセットにはなりません。

更新そのものが届いていない場合は、getWebhookInfoによる配信診断へ進みます。配信障害と、アプリケーションがコールバックを無視している状態では、修正箇所が異なります。

コールバックは届くが読み込み表示が続く

実際の更新と次の対応表を照合します。

受信フィールド	用途
callback_query.id	answerCallbackQuery の callback_query_id に渡す
callback_query.data	存在する場合、アプリケーションへの入力として扱う
callback_query.message	存在する場合のメッセージ情報。常にあるとは限らない
callback_query.inline_message_id	存在する場合、インラインモード経由のメッセージを識別する

通常のBotメッセージとインラインモードのメッセージでは、提供される情報が異なります。常に callback_query.message.chat を参照する実装では、応答処理に到達する前にエラーになる可能性があります。

結果を確認したい場合は、answerCallbackQuery を個別に呼び出します。Botトークンを漏らさず、実際の成功やエラーを記録してください。AI、CRMなどの時間がかかる処理を待ってから操作に応答する設計は避けます。

読み込みは終わるが業務処理が誤っている

コールバックデータは入力であり、操作権限の証明ではありません。Telegramは、クエリの元メッセージに、そのデータを持つボタンが存在しない場合があると注意しています。許可された操作、ユーザー権限、サーバー上の最新状態を検証する設計を推奨します。

仮の承認フローなら、クリックへの応答だけで申請を承認済みにしてはいけません。リクエストを検証し、正当な状態遷移を一度だけ実行し、実際の結果を別途表示します。再配信の重複排除と、繰り返しクリックによる二重実行の防止は、別々の対策です。

Webhookだけでなく操作全体をテストする

公開前に、次のケースを確認してください。

• 正常なコールバックに、通知文なしで応答できる。
• 遅い業務処理が操作への応答をブロックしない。
• message がなくてもハンドラーが異常終了しない。
• 未知または古いデータが、権限のない操作を引き起こさない。
• 再配信や繰り返しクリックで、取り消せない操作を重複実行しない。

これは推奨する受け入れテストであり、実施済みの結果やTelegramの応答時間保証ではありません。

UnifyPortとの役割分担

Botのインラインキーボードとコールバック応答には、Telegram公式Bot APIを使い続けてください。UnifyPortの非公式インターフェースは、接続したメッセージングアカウント向けに別の正規化イベント契約を提供します。公開のWebhookイベント一覧には message.received がありますが、callback_query イベントや answerCallbackQuery 操作は記載されていません。メッセージイベントをコールバックと読み替えたり、統一WebhookがBotのボタンに応答すると想定したりしないでください。

LINEなどを含むアカウント単位の受信も必要なら、その受信処理をBotの操作ハンドラーから分離します。UnifyPortの配信リファレンスではレスポンス本文を破棄すると定義しています。そこにBot APIメソッドのJSONを返しても、コールバック応答は実行されません。

よくある質問

HTTP 200でTelegramボタンの読み込みは止まりますか？

それだけでは止まりません。HTTPは更新の受領確認であり、コールバックには answerCallbackQuery が必要です。

answerCallbackQueryに文字列は必須ですか？

いいえ。text は任意なので、通知文を表示せずに応答できます。

callback_query_idにはメッセージIDを渡しますか？

いいえ。受信した CallbackQuery の id を使います。

統一メッセージWebhookで代用できますか？

UnifyPortの公開契約では代用できません。公式Telegram Bot連携側にコールバック処理を残してください。

次のステップと出典

管理されたテストでボタンを一度押し、callback_query の受信から answerCallbackQuery の実際の結果まで追跡します。アカウント単位の受信も必要なら、処理を共通化する前に標準Webhookイベント契約を確認してください。

公式情報の確認日：2026-09-22。Telegram Bot API：CallbackQuery、answerCallbackQuery、InlineKeyboardButton、allowed_updates。