変数置換とフォーミュラ

変数置換とは {{...}} 形式の変数で、リアクションが発火する際にメッセージテキスト・アクションのフィールド・ボタンテンプレートに挿入されます。認識されない変数置換はそのまま残ります。変数に加えて、計算用のフォーミュラもあります。メッセージエディターの**「変数置換」**ボタンを使って変数を挿入できます。

送信者データ

  • {{first_name}}、{{last_name}} — 名前と苗字。
  • {{username}} — ユーザーの @username。
  • {{user_id}} — 数値の Telegram ID。

イベントとチャットのデータ

  • {{text}}（{{received_message}} とも）— 受信メッセージのテキスト。
  • {{message_id}}（{{received_message_id}} とも）— 受信メッセージの ID。
  • {{chat_id}}、{{chat_title}}（{{chat_name}} とも）— イベントが発生したチャット。
  • {{topic_id}}、{{topic_url}} — トピック（フォーラム用）。

日付と時刻

  • {{date}} — 日付（YYYY-MM-DD）、{{time}} — 時刻（HH:MM）、{{datetime}} — 日時。
  • フォーマット: {{date:DD.MM.YYYY HH:mm}} — トークン YYYY、YY、MM、DD、HH、mm、ss。

ユーザーパラメータ

  • {{param.key}}（{{params.key}} または {{recipient.key}} とも）— 購読者パラメータの値。パラメータは「パラメータを変更」・「メッセージを保存」アクションやダイアログの返答によって設定されます。

実行コンテキスト（ctx）

  • {{ctx.key}}（{{context.key}} とも）— 現在の実行の一時値: 受信 Webhook のデータ、アクションの結果（ウェブリクエスト、ソースへのクエリ、AI）、ボタンデータの復元（Carry）、ループの要素。
  • リストのループでは、要素は自身のエイリアスで参照できます。例: {{item.name}}。

フォーミュラ

{{= 式}} 構文はテキスト内で式を直接評価します。同じエンジンが**「計算」**アクションと意思決定テーブルの条件でも機能します。式内ではパラメータや ctx の値を名前で参照でき、算術・比較・論理演算や多数の関数（ROUND、IF、CONCAT など。ロシア語エイリアスも利用可）を使用できます。

例: {{= ROUND(param.total * 0.9) }} — パラメータの合計から10%割引。

完全な構文と関数一覧は フォーミュラ セクションを参照してください。

変数置換における HTML

メッセージは HTML マークアップで送信されます。置換された値がレイアウトを壊さないように（例えばユーザー名に < が含まれる場合）、置換された値はデフォルトでエスケープされます。HTML 文字は安全なテキストに変換されます。リアクションのテキストに直接書いたタグ（<b>、<a> など）はそのまま残ります。

値そのものに整形済みのマークアップが含まれている場合（例えば <b>...</b> を含むアナウンスがパラメータに保存されているとき）に、それをそのまま挿入したいときは、変数置換の前に & を付けます。

  • {{& key}} — {{...}} 変数置換の生挿入。
  • {&user:key}、{&recipient:key}、{&global:key} — namespace 変数置換の生挿入。

& プレフィックスはその 1 つの変数置換に対してのみエスケープを無効にします。値のソースの信頼性はあなたが保証することになります。購読者が制御するトークン（{{first_name}} など）はエスケープしたままにしておくのが安全です。

他のビルダーからボットをインポートする際、namespace 変数置換 {user:…}/{recipient:…}/{global:…} は自動的に生形式 {&…} に移行されます。これらには通常、整形済みのマークアップを含む値が入っており、元のビルダーでの動作に合わせています。

フォーマットに関する注意

{{...}} 変数置換は、テキスト・キャプション・リクエストボディ・ボタンテンプレートで機能します。パラメータ名と ctx キーは短くラテン文字で付けてください（email、total、order_id）— 変数置換の入力が簡単になります。

次のステップ