GetMyBot 知識庫

動態按鈕與參數

以按鈕展示商品、記住選擇並交給下一條反應;附 Carry、有效期和永久參數範例。

本頁內容

機器人展示三件商品,每件都有「購買」按鈕。客戶選了洋裝,即使之後又看過其他商品,下一條反應也必須取得洋裝的資料。

動態按鈕按商品清單建立按鈕,Carry 則記住每顆按鈕對應的商品。兩者都在傳送訊息動作的訊息區塊設定。

客戶看到的商品按鈕儲存的資料
外套,12,000 ₽ · 購買product_id=101、price=12000
洋裝,8,000 ₽ · 購買product_id=102、price=8000
運動鞋,6,000 ₽ · 購買product_id=103、price=6000

按下第二顆按鈕會傳入 product_id=102,機器人無須靠相同的「購買」文字猜測商品。

從列表動態生成按鈕

**「從列表動態生成按鈕」**區塊將 ctx 中的陣列展開為鍵盤:每個陣列元素對應一個按鈕。需設定四項:

  • 列表 — 上下文中陣列的鍵(over),例如 ctx.products。陣列通常由「查詢來源」、「Web 請求」或計算動作寫入。
  • 元素別名 — 模板中元素的存取名稱(as,預設為 item)。
  • 每行按鈕數 — 每行放幾個按鈕(columns,預設為 1)。
  • 按鈕模板 — 普通按鈕,但其文字和欄位支援以別名進行變數替換:{{item.name}}、{{item.price}} 等。

傳送時,模板為每個元素渲染一次,生成與列表元素數量相同的按鈕。這樣就能建構目錄、集合記錄列表及資料驅動的選單。

範例

假設 ctx.products 的每項都有 id、name、price:

  1. 設定清單 ctx.products、別名 item,每列一顆按鈕。
  2. 按鈕文字填 {{item.name}} · {{item.price}} ₽。
  3. 選呼叫反應並指定結帳反應。
  4. Carry 鍵填 product_id,值填 {{item.id}}。
  5. 結帳反應以 {{ctx.product_id}} 讀取所選商品。

依序按第二顆和第一顆,兩次都應取得各自按鈕的商品 ID。

點擊時的參數(Carry)

「Carry — 點擊時的資料快照」區塊為按鈕附加一組鍵 → 值配對,這些值在傳送訊息時計算並固定。點擊時這些值會恢復至 ctx——因此每個按鈕都攜帶自己的參數(per-invocation),即使一條訊息中有數十個按鈕也互不干擾。

  • carry 鍵 — 點擊時值在 ctx 中的名稱。
  • carry 值 — 含變數替換的模板({{item.id}}、{{param.order_id}}、{{ctx.x}}),在傳送時計算。
  • 一次性(single_use)— 按鈕資料在第一次點擊後失效。
  • 按鈕資料有效期(ttl_seconds)— 以秒計算;3600 是一小時,0 使用目前預設的 30 天,並非永不過期。

到期後舊資料不可用,應讓客戶重新開啟目錄。每次傳送的每顆按鈕都有獨立資料,即使按鈕文字和目標反應相同;技術上稱為 per-invocation。

透過按鈕設定參數(set_params)

除了 Carry 快照,按鈕還能在點擊時直接設定訂閱者的參數——即**「參數」欄位(set_params)。與 Carry(ctx 中的臨時值)不同,set_params 寫入使用者的永久參數**({{param.鍵}}),這些參數在不同執行間持續保留。訊息區塊中也有相同欄位——此時參數在傳送時而非點擊時設定。

按鈕點擊時還可以設定及移除標籤——使用與訊息區塊相同的欄位。

三種機制的區別

  • Carry — ctx 中的快照,存活至點擊時,繫結至特定按鈕,支援 TTL 及一次性使用。
  • 按鈕上的 set_params — 點擊時寫入訂閱者的永久參數。
  • 區塊上的 set_params — 傳送訊息時寫入永久參數。

對「選商品再下單」的流程,使用動態按鈕 + Carry:把清單變成按鈕,每顆按鈕儲存對應的 product_id。

延伸閱讀