變數替換與公式

變數替換是 {{...}} 形式的變數，在反應觸發時插入訊息文字、動作欄位與按鈕範本中。無法識別的替換將保留原樣。除了變數外，還有用於計算的公式。訊息編輯器中的**「變數替換」**按鈕可協助插入變數。

傳送者資料

  • {{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) }} — 從參數中取得金額並計算 90 折價格。

完整語法與函式清單請參閱公式。

變數替換中的 HTML

訊息以 HTML 標記傳送。為避免替換後的值破壞版面（例如使用者名稱中包含 <），替換的值預設會被跳脫：HTML 字元會轉為安全文字。你直接寫在反應文字中的標籤（<b>、<a> 等）則保持不變。

如果某個值本身已包含現成的標記（例如儲存在參數中、帶有 <b>...</b> 的公告），而你想原樣插入，請在變數替換前加上 &：

  • {{& key}} — 用於 {{...}} 變數替換的原始插入。
  • {&user:key}、{&recipient:key}、{&global:key} — 用於 namespace 變數替換的原始插入。

& 前綴僅對該單一變數替換關閉跳脫——你需為值來源的可信度負責。受訂閱者控制的權杖（{{first_name}} 等）最好保持跳脫。

從其他建構工具匯入機器人時，namespace 變數替換 {user:…}/{recipient:…}/{global:…} 會自動遷移為原始形式 {&…}——它們通常存放帶有現成標記的值，與來源建構工具的運作方式一致。

格式注意事項

{{...}} 替換適用於文字、說明、請求主體與按鈕範本。請使用簡短的英文參數名稱與 ctx 鍵值（email、total、order_id）——這樣在引用時更為方便。

後續步驟