OpenClawのTelegramリッチメッセージと承認

Telegramボットが送れるものは、テキストだけではありません。書式付きのブロック、メッセージの下のキーボード、Mini Appのランチャー、他人のメッセージへのリアクション、2つのボタンが付いた承認プロンプトもあります。OpenClawはこれらを少数の設定キーとメッセージアクションで提供しており、そのほとんどは有効にするまでオフです。ここでは、書式の取り決め、ボタンのスコープ、ゲート付きのアクション、そしてexec承認がTelegram内で承認者に届く仕組みを紹介します。

書式

• 送信テキストはデフォルトで標準のTelegram HTMLを使います。現在のクライアント全体で読め、太字、斜体、リンク、コード、スポイラー、引用に対応しています。フェンスで囲んだコードは、ブロック内のフェンスの例も含めて、内容と空白がそのまま保たれます。Bot API 10.3のリッチ専用ブロック（ネイティブのテーブル、details、リッチメディア、数式）は、オプトインしない限り使われません。
• rich-messagesフラグをオンにすると、エージェントには、このボットまたはアカウントでリッチメッセージが使えることと、対応するMarkdownとHTMLアイランドの記述ルールが伝えられます。MarkdownはOpenClawのMarkdown中間表現を経て、見出し、テーブル、details、チェックリスト、リッチメディア、数式、地図、コラージュといった型付きのリッチブロックとして描画されます。一方、メディアのキャプションは引き続き1024文字までのHTMLキャプションを使います。通常のリッチ本文では解析されたスペースと改行が保たれ、エンティティは一度だけデコードされ、エスケープされたタグは目に見えるテキストのまま残ります。未対応のHTMLは、その中のMarkdownを抑制することなく表示されたままになり、長いリッチテキストはTelegramの上限に合わせて自動的に分割され、20列の上限を超えるテーブルはコードブロックにフォールバックします。
• このフラグは、クライアントの互換性のためにデフォルトでオフです。現在のDesktop、Web、Android、サードパーティのクライアントの一部が、受け付けたリッチメッセージを未対応のメッセージとして表示するからです。ボットで使うすべてのクライアントが描画できる場合を除き、オフのままにしてください。現在のセッションでリッチメッセージがオンかオフかは、statusコマンドで確認できます。
• リンクプレビューはデフォルトでオンで、link-previewキーをfalseにすると、リッチテキストでのエンティティの自動検出が無効になります。40万から60万ドルのような通貨の範囲が数式として解析されないのも、モデルのテキストをTelegramのリッチMarkdownの記号から遠ざけているためです。

Mini Appのボタンは、ユーザーとボットの間のプライベートチャットでのみ機能します。

インラインボタン

インラインボタンの機能には、off、dm、group、all、allowlistの5つのスコープがあり、デフォルトはallowlistです。チャネル単位で設定し、アカウントごとに上書きできます。旧来の配列形式はallに対応し、capabilitiesの配列が空のアカウントはチャネルのcapabilitiesを継承し、明示的なoffはボタンを無効にします。ask-userツールは、単一選択の質問1つにこれらのネイティブコントロールを使い、選択肢ごとに1行を割り当て、Telegramの返信入力を開く「Other」の選択肢を付けます。メッセージアクションはbuttonsブロックを含むプレゼンテーションを持ち、各ボタンはラベル、アクション、successやdangerといった任意のスタイルで構成されます。callbackアクションはその値を返し、web-appアクションはMini AppのURLを開きますが、これはユーザーとボットの間のプライベートチャットでのみ機能します。登録済みのプラグインのインタラクティブハンドラーが処理しないコールバック値は、callback dataというプレフィックスを付けたテキストとしてエージェントに渡されます。永続的な受信処理では、コールバックの応答確認は更新が保存された直後に送られ、そのチャットのレーンで先行するハンドラーを待ちません。そのため、Telegramは読み込み中の表示を早めに消しますが、ボタンのアクション自体は引き続き通常の認可と順序どおりの処理に従います。

アクションと承認

• アクションは次のとおりです。ターゲット、内容、任意のメディアURL、返信ID、スレッドIDを指定するsend-message、チャット、メッセージ、絵文字を指定するreact、任意のチャットとlimitを指定するemoji-list、delete-message、内容またはキャプションと任意のインラインボタンを指定するedit-message（ボタンだけの編集ではreply markupが更新されます）、そして名前と任意のアイコン色またはカスタム絵文字を指定するcreate-forum-topicです。加えて、send、react、delete、edit、sticker、sticker-search、topic-createというエイリアスがあります。send-message、delete-message、reactions、stickerのゲートはデフォルトで無効で、reactionsはreactとemoji-listの両方をカバーします。editとフォーラムトピックのアクションは、専用のトグルなしで有効になっています。また、実行時の送信では、送信のたびにシークレット参照を解決し直すのではなく、起動時またはリロード時の設定とシークレットのスナップショットを使います。
• emoji-listは、現在の信頼されたチャットとアカウントで許可されているリアクションを確認します。エージェントは他のチャットを確認できませんが、直接のオペレーターは別のチャットIDを渡せます。limitはデフォルトで100で、100を超えることはできません。制限のないチャットでは、すべて許可されていることを示す注記とともに標準のリアクションが返されます。リアクションが拒否されると、照会自体が失敗した場合を除き、許可されている標準リアクションとカスタム絵文字の識別子の短いサンプルが返されます。reactには、Unicodeの絵文字または数値のカスタム絵文字識別子をそのまま渡します。
• exec承認は承認者のDMで機能し、任意で発生元のチャットやトピックにもプロンプトを投稿できます。承認者は数値のユーザーIDである必要があります。enabledキーをautoにすると、解決できる承認者が1人以上いる場合に有効になります。approversリストは、オーナー許可リストにある数値のオーナーIDにフォールバックします。ターゲットはデフォルトでdmで、代わりにchannelとbothも指定でき、エージェントとセッションのフィルターで対象を絞り込めます。誰がボットと会話できるかを決める許可リストによって誰かが承認者になることはありませんが、最初に承認されたペアリングがオーナーリストの初期値になります。チャネルへの配信ではコマンドのテキストが表示されるため、channelやbothは信頼できるグループでのみ使うべきです。フォーラムトピックに届いたプロンプトは、その後のやり取りでもそのトピックを保ちます。承認はデフォルトで30分後に期限切れになり、インラインの承認ボタンを使うには、ボタンの機能がターゲットのサーフェスを許可している必要があります。pluginというプレフィックスの付いた承認IDはプラグイン承認で解決され、それ以外はまずexec承認での解決が試みられます。

TelegramでのOpenClawは、これらのサーフェスの土台となるチャネルの記事で、OpenClawのTelegramメッセージの挙動は、その下にある配信モデルです。

チャネルをまたぐボタン

buttonsブロック、コールバック値、承認プロンプトは、ネイティブのコンポーネントを持つすべてのチャネルで同じ形を保ちます。だからこそエージェントは、どこで答えが返ってくるかを知らなくても、はい・いいえで答える質問ができるのです。OpenClawのDiscordコンポーネントと承認ではこの取り決めのDiscord側を、OpenClawのリアクションではreactとemoji-listが実装するリアクションのセマンティクスを紹介しています。

Dialiでは

Telegramは、Dialiがダッシュボードから接続するチャネルの1つで、生成されたランタイム設定はリリースごとに置き換えられます。そのため、ここで紹介した書式とボタンのキーは、手で編集する設定ではなく、ホスト型ボットにできることを表しています。DialiでのTelegramはDialiでこのチャネルを使う方法、Dialiのセキュリティはボットが取り得るすべてのアクションに適用される境界です。

• デフォルトはHTML。リッチブロックは、すべてのクライアントが描画できる場合にのみ使います。
• ボタンはスコープに従い、Mini Appはプライベートチャットでのみ開きます。
• 送信、削除、リアクション、ステッカーは、ゲートで有効にするまでオフのままです。