動態按鈕與參數
以按鈕展示商品、記住選擇並交給下一條反應;附 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:
- 設定清單
ctx.products、別名item,每列一顆按鈕。 - 按鈕文字填
{{item.name}} · {{item.price}} ₽。 - 選呼叫反應並指定結帳反應。
- Carry 鍵填
product_id,值填{{item.id}}。 - 結帳反應以
{{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。