チュートリアル July 20, 2026

TelegramグループでエフェメラルBotメッセージを送る方法

Telegram Botは、グループまたはスーパーグループ内で、指定した1人のユーザーとBotだけが見られるエフェメラルメッセージを送信できるようになりました。通常のBotは、対象となるコールバックまたはエフェメラルメッセージを受けてから15秒以内に返信する必要があります。チャット管理者のBotは、Bot以外のメンバーであればいつでも送信できます。ただし、特に受信者がオフラインの場合、配信は保証されません。

要点

Bot API 10.2では、2026年7月14日にユーザー限定の非公開Botメッセージとエフェメラルコマンドが追加されました。
ユーザーが実行したコマンドを他のメンバーやBotに見せたくない場合は、コマンドの is_ephemeral フィールドを true にします。
管理者ではないBotには、直近の callback_query_id または reply_parameters.ephemeral_message_id が必要で、応答期限は15秒です。
管理者Botはトリガー識別子なしでBot以外のメンバーを指定できますが、その場合も配信はベストエフォートです。
エフェメラルメッセージはUI上のフィードバックであり、永続的な監査ログでも、プラットフォーム共通のメッセージ種別でもありません。

TelegramのエフェメラルBotメッセージとは？

エフェメラルBotメッセージとは、グループまたはスーパーグループのタイムライン上で1人のユーザーだけに表示される非公開の応答です。他のグループメンバーや他のBotには見えません。Telegramは、ウェルカムメッセージ、非公開のAI要約、エラー、確認、状況に応じたヒント、ボタンメニューなどを適した例として挙げています。

これは Telegram Guest Mode とは異なります。Guest Modeは、Botが参加していないチャットでどのように呼び出されるかを決める機能です。エフェメラルメッセージは、特定のコマンドやBotの応答を誰が見られるかを決めます。また、可視性ではなくフォーマットを変更した Bot API 10.1のリッチメッセージとも別の機能です。

Telegramによれば、このような対話は一定時間後、またはアプリの再起動時に自動的に消えることがあります。公式ドキュメントには固定の保持期間が示されていません。承認、支払い状況、サポート上の決定など、永続性が必要な業務イベントの唯一の記録として、表示中のメッセージを使わないでください。

グループでユーザー限定返信を送れるBotの条件

権限には2つの経路があります。必要な識別子と配信動作が異なるため、ハンドラーを設計する前にどちらを使うか決めてください。

Botの状況	送信できるタイミング	必要なトリガーデータ	配信範囲
すべてのBot	対象となる受信アクションから15秒以内	`callback_query_id` または `reply_parameters.ephemeral_message_id`	アクションを発生させたクライアントアプリ
チャット管理者のBot	Bot以外のメンバーへいつでも送信可能	どちらのトリガー識別子も不要	複数のアクティブなクライアントに届く場合があるが、保証はされない

どちらの経路でも、閲覧するユーザーは receiver_user_id で指定します。送信するエフェメラルメッセージはグループとスーパーグループだけで利用できます。ダイレクトメッセージでの会話を置き換えるものではありません。

配信に関する注意点は重要です。Telegramは、特にユーザーがオフラインの場合、受信を保証しないと明記しています。このメッセージは便利なUIフィードバックとして設計してください。操作によってサーバーの状態が変わる場合は、先にその状態を永続化し、ユーザーが後から再取得できるようにします。

手順1：エフェメラルコマンドを宣言する

setMyCommands を使い、実行内容を非公開にしたいコマンドの is_ephemeral を true にします。次の仮想的なコマンドでは、ユーザーの /summary リクエストが他のグループメンバーやBotに表示されません。

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {
        "command": "summary",
        "description": "Summarize this discussion for me",
        "is_ephemeral": true
      }
    ],
    "scope": {
      "type": "all_group_chats"
    }
  }'

is_ephemeral が影響するのは、ユーザーが送信するコマンドです。それだけで、その後にBotが送るすべてのメッセージの受信者が決まるわけではありません。送信リクエストには、正しいチャット、閲覧ユーザー、そしてBotが管理者でない限り、対象となるトリガーが引き続き必要です。

手順2：グループ内でユーザー限定返信を送る

コールバックを起点とする応答では、対応する送信メソッドを chat_id、receiver_user_id、callback_query_id とともに呼び出します。Bot API 10.2では、sendMessage のほか、対応するメディア、ファイル、連絡先、位置情報の各メソッドに2つのエフェメラル関連パラメーターが追加されました。

次の仮想的なリクエストは、スーパーグループ内の1人のメンバーに確認メッセージを送ります。

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": -1001234567890,
    "receiver_user_id": 424242424,
    "callback_query_id": "4382bfdwdsb323b2d9",
    "text": "Your report is ready. Only you can see this confirmation."
  }'

リクエストは15秒の期限内に送信します。トリガーがコールバッククエリではなく受信したエフェメラルメッセージの場合は、代わりに reply_parameters.ephemeral_message_id を指定して返信します。通常の message_id で代用しないでください。Bot API 10.2では、エフェメラル識別子がある場合に限って message_id を省略できると定められています。

管理者Botが直近のアクションなしでメッセージを開始する場合は、callback_query_id とエフェメラル返信先を省略できます。ただし、グループの chat_id と、Botではないメンバーの receiver_user_id は指定する必要があります。

手順3：エフェメラル識別子で編集・削除する

Telegramの Message オブジェクトで返された ephemeral_message_id を、chat_id および receiver_user_id とともに保存します。通常の編集・削除メソッドは、このメッセージ種別のライフサイクルAPIとして適切ではありません。

次の専用メソッドを使用します。

editEphemeralMessageText
editEphemeralMessageMedia
editEphemeralMessageCaption
editEphemeralMessageReplyMarkup
deleteEphemeralMessage

たとえば、テキストを編集するには3つの識別フィールドがすべて必要です。

{
  "chat_id": -1001234567890,
  "receiver_user_id": 424242424,
  "ephemeral_message_id": 781,
  "text": "The report is ready to download."
}

Telegramは、編集・削除イベントがオフラインのユーザーに届かない場合があることも示しています。ライフサイクルの呼び出しはベストエフォートのUI更新として扱ってください。ユーザーが機密情報を見た、または見られなくなったことの証明にはなりません。

実装チェックリスト

応答を分類する。 グループの文脈内で見せる個人的なフィードバックにはエフェメラルメッセージを使い、チームが保持すべき記録には使いません。
トリガーをすぐに取得する。 callback_query_id または受信した ephemeral_message_id は、15秒の応答経路を満たすために必要な期間だけ保持します。
サーバー側で認可する。 非表示であることは認可を意味しません。要約、メニュー、操作を生成する前に、呼び出し元がそれを要求できるか確認します。
永続的な状態を別途保存する。 承認、ジョブの状態、サポート操作は、UIで受け付けを通知する前に自社のデータベースへ保存します。
専用のライフサイクルメソッドを使う。 編集・削除用に、chat_id、receiver_user_id、ephemeral_message_id を1つの検索用タプルとして保存します。
未配信を前提に設計する。 ユーザーが結果を確実に再取得できる必要がある場合は、通常のプライベートチャット、ダッシュボード、再試行の経路を用意します。
権限とクライアントをテストする。 通常のBot、管理者Bot、グループとスーパーグループ、複数のアクティブな端末、オフラインの受信者を網羅します。

UnifyPortが適する範囲と適さない範囲

Telegramのエフェメラルメッセージは、Telegram Bot API固有の機能です。現在のUnifyPort APIリファレンスでは、POST /v1/messages に対する receiver_user_id、callback_query_id、エフェメラルメッセージ専用の編集・削除メソッドは記載されていません。製品がこのユーザー限定のグループUIに依存する場合は、Telegramの公式Bot APIを使用してください。

UnifyPortが解決するのは別のレイヤーです。対応アカウントで受信した通常のメッセージは、正規化された message.received イベントとして届き、対応する標準返信はプロバイダー共通の1つのメッセージAPIで送信できます。Telegram、WhatsApp、LINE、Zalo、TikTok、Xをまたぐ永続的なキューが必要なチームには有効です。一方、他のプラットフォームのメッセージをTelegramのエフェメラル返信に変換したり、Telegram固有の可視性の意味を維持したりするものではありません。

実際の要件がTelegram専用のBot画面ではなく、複数チャネルのサポートである場合は、Telegramのクロスチャネル自動化ガイドでアーキテクチャの境界を確認してください。

制約とトレードオフ

ユーザーをグループから移動させずに、Botが非公開の確認、エラー、メニュー、要約を表示する必要がある場合は、公式Bot APIの機能が適しています。Telegramクライアントにネイティブなユーザー単位の可視性を提供し、テキストに加えて複数のメディアやユーティリティメッセージ種別にも対応します。

配信保証が必要な通知、コンプライアンス記録、永続的なサポート履歴、確実に撤回できなければならない機密情報には使わないでください。オフラインユーザーへの配信、編集、削除は保証されず、メッセージが消える可能性もあり、公式ドキュメントは固定の保持期間を約束していません。非公式インターフェースでも、こうしたプラットフォーム上の保証は変えられず、他のチャネルにエフェメラル動作を追加することもできません。

FAQ

Telegram Botはグループ内の1人だけに見えるメッセージを送れますか？

はい。グループまたはスーパーグループで receiver_user_id を指定し、15秒以内の有効なトリガー経路、またはチャット管理者の経路を満たします。エフェメラルメッセージを見られるのは、指定されたユーザーとBotだけです。

Botはグループ管理者である必要がありますか？

必須ではありません。関連する callback_query_id または受信したエフェメラル返信の識別子があれば、どのBotでも15秒以内に応答できます。管理者Botは、それらのトリガー識別子がなくても、Bot以外の任意のメンバーにエフェメラルメッセージを開始できます。

TelegramのエフェメラルBotメッセージはどのくらい残りますか？

Telegramは固定の保持期間を公開していません。公式ドキュメントでは、一定時間後またはアプリの再起動時に自動的に消えることがあるとされているため、永続ストレージとして扱わないでください。

オフラインのユーザーもエフェメラルメッセージを受信できますか？

特にユーザーがオフラインの場合、配信は保証されません。編集・削除イベントにも同じ制約があります。重要な結果には、後から再取得できる経路を用意してください。

エフェメラルメッセージとTelegram Guest Modeは同じですか？

いいえ。Guest Modeは、Botがチャットに参加していない状態でどのように関与できるかを制御します。エフェメラルメッセージは、グループ内のコマンドや返信を誰が見られるかを制御します。組み合わせて使うことはできますが、解決する課題は異なります。

次のステップ

Telegram固有の処理は、公式の Bot APIエフェメラルメッセージリファレンスに沿って実装してください。ワークフローの残りの部分で複数プロバイダーの永続的なメッセージを扱う場合は、共通ハンドラーを設計する前に UnifyPortのプロバイダー別メッセージ対応表を確認してください。

出典

公式情報の確認日：2026年7月20日。