公式
計算金額、折扣或依條件選擇回覆;了解文字中的短公式與「計算」動作的差別。
本頁內容
公式讓機器人計算並選擇值。例如 price = 500、qty = 3 時,{{= price * qty}} 會得到 1500。這兩個值須先存入客戶參數或目前反應的暫存資料。
簡單計算可直接寫在訊息中;清單、日期或俄文函式名稱則用計算動作。GetMyBot 有兩種不同的公式語言:
- 短表示式:用於算術、比較和簡單文字。可放在訊息的
{{= 表示式}}、計算動作的公式(expr)模式,或決策表條件中。 - 進階公式:類似試算表,支援清單、JSON、日期、雜湊、
LAMBDA和俄文函式名稱。可用於計算動作的進階公式(formula)、答案驗證及公式測試器。
公式可用的位置
| 位置 | 語言 |
|---|---|
訊息中的 {{= 表示式}} | 短表示式 |
「計算」的「公式」模式(expr) | 短表示式 |
「計算」的「決策表」模式(rules) | 「當」使用短表示式;「則」與預設值是支援 {{...}} 的一般文字 |
「計算」的「進階公式」模式(formula) | 進階公式 |
| 答案驗證的「符合公式」 | 進階公式 |
公式測試器 test_formula | 進階公式 |
「計算」動作
每個動作只可選一種模式:公式(expr)、決策表(rules + default,第一條成立規則生效,否則使用預設值),或進階公式(formula)。
結果可存入目前反應的 ctx(save_to_ctx)或客戶參數(save_to_param),兩者可同時選,但至少要選一個。例如結果存為 ctx.discount 後,可用 {{ctx.discount}} 插入。
短表示式、決策表條件及規則值各最多 4,096 位元組;進階公式最多 16,384 位元組;決策表最多 64 條規則。限制按位元組計算,例如一個俄文字母佔 2 位元組。
{"type":"compute","params":{"formula":"IF({total} > 1000; \"批發\"; \"零售\")","save_to_ctx":"segment"}}
短表示式
語法
- 運算子:
+ - * / %、比較== != < > <= >=、邏輯&& || !、條件選擇條件 ? 是 : 否、括號( )。 - 常值:
42、3.14、"你好"或'你好'、true、false。 - 資料:不用大括號,直接以名稱讀取參數與
ctx,例如price * qty、ctx.total、param.total。未知名稱是空字串。 - 函式:
名稱(參數1, 參數2),用逗號分隔。
函式
短表示式只支援小寫的 len、upper、lower、trim、concat、round、floor、ceil、abs、min、max。min、max 恰好接受兩個參數,concat 可接受任意數量。len 和進階公式的 LEN 都按讀者看到的字元計算,帶重音字母、旗幟或由多個碼位組成的表情符號也算一個字元。
短表示式沒有俄文函式別名。{{= }} 中若出現未知函式,整段會原樣留在訊息中。
進階公式
進階公式語法
- 參數用分號分隔,例如
IF({total} > 1000; "批發"; "零售")。 - 運算子:算術
+ - * /、字串相接&、比較= != <> < > <= >=;相等只用單個=。邏輯使用AND、OR、NOT函式。 - 字串可使用單引號或雙引號。字串內的
""不代表引號;若需在 HTML 屬性中放引號,可交替使用兩種引號,例如"<a href='tg://user?id=" & r.user_id & "'>個人檔案</a>"。 - 資料用單層大括號:
{鍵}讀取ctx;{text}、{answer}是傳入文字;{user:鍵}是訂閱者參數;{global:鍵}是全域參數。 - LAMBDA:
LAMBDA(r; 表示式)定義FILTER、FOREACH、ARRAYFIND、REDUCE逐項處理規則。JSON 物件欄位用r.user_id等寫法。 - 結果會轉成文字。要保存清單,先用
TOJSON,下次計算時再用FROMJSON。 - 函式名稱不分大小寫,也支援下列俄文別名。
進階公式函式
括號內是俄文別名。以下函式只能在進階公式中使用。
數學
SUM(СУММ)、AVERAGE(СРЗНАЧ)、MAX(МАКС)、MIN(МИН)、MOD(ОСТАТ)、POW(СТЕПЕНЬ)、SQRT(КОРЕНЬ)、PI(ПИ)、ROUND(ОКРУГЛ)、CEIL(ОКРВВЕРХ)、FLOOR(ОКРВНИЗ)、TRUNC(ОТБР)、ABS、RANDBETWEEN(СЛУЧМЕЖДУ)。
文字
LEN(ДЛСТР)、LEFT(ЛЕВСИМВ)、RIGHT(ПРАВСИМВ)、MID(ПСТР)、LOWER(СТРОЧН)、UPPER(ПРОПИСН)、UPPERFIRST(ПРОПИСНПЕРВ)、REPEAT(ПОВТОР)、CONCAT(СЦЕПИТЬ)、SUBSTITUTE(ПОДСТАВИТЬ)、FIND(НАЙТИ)、SEARCH(ПОИСК)、FIELD(ПОЛЕ)、TRIM、LTRIM、RTRIM、PADLEFT、PADRIGHT、SPLIT、JOIN、STARTSWITH、ENDSWITH、CONTAINS、NL。
邏輯
IF(ЕСЛИ)、AND(И)、OR(ИЛИ)、NOT(НЕ)、EMPTY、ISNUMBER(ЕЧИСЛО)、COALESCE。
清單
SORT、RSORT、UNIQUE、FILTER、FOREACH、REDUCE、INDEX、SLICE、COUNTA(СЧЁТЗ)、COUNTUNIQUE、ARRAYADD、ARRAYREMOVE、ARRAYREPLACE、ARRAYFIND、PAIRUP(СОСТАВИТЬПАРЫ)。
PAIRUP(items; idField; seed [; tagsField]) 可把參與者分成「random coffee」配對。人數為奇數時會有一組三人。可用 "|a|b|" 字串或陣列標籤,儘量把有共同標籤的人分開;相同資料和 seed 會得到相同結果。最多 10,000 人、每人 64 個標籤;大量重複標籤可能無法避免所有交集,但所有人都會被分組。尋找記錄一次最多讀 10,000 列,進階公式結果最多 4 MB。
日期與時間
TODAY(СЕГОДНЯ)、NOW(ТДАТА)、DATEADD、DATESUB、DATEDIF(РАЗНДАТ)、DATEFORMAT、DATEVALUE、WEEKDAY(ДЕНЬНЕД)。
JSON
TOJSON、FROMJSON、JSONPATH、JP、JSONOBJECT、JSONARRAY、KEYS、VALUES。
加密與編碼
HASH(ХЭШ)、TOBASE64、FROMBASE64、FROMJWT、FROMJWK。
參數
PARAMID、PARAMREPLACE、PARAMREMOVE。
範例
訊息中的短表示式:
- 訂單總額:
{{= price * qty}}。 - 將三分之一四捨五入:
{{= round(total / 3)}}。 - 依條件選擇:
{{= param.total > 1000 ? "批發" : "零售"}}。 - 組合文字:
{{= concat("訂單編號 ", ctx.order_id)}}。
「計算」動作中的進階公式:
- 九折金額:
ОКРУГЛ({user:total} * 0.9)。 ctx清單筆數:СЧЁТЗ(FROMJSON({items}))。- 對「尋找記錄」放入
ctx.rows的記錄產生穩定排序;資料和鹽值不變時順序也不變:
{"type":"compute","params":{"formula":"TOJSON(SORT(FOREACH(FROMJSON({rows}); LAMBDA(r; HASH(\"sha256\"; r.user_id & \"-salt\") & \"|\" & r.user_id))))","save_to_ctx":"order"}}
「符合公式」答案驗證應在接受時回傳空文字,拒絕時回傳錯誤訊息,例如 IF(ISNUMBER({answer}); ""; "請輸入數字")。
測試公式
測試器只檢查進階公式,回傳結果或語法錯誤,不會儲存資料:
- 在「符合公式」答案驗證區填入範例答案,按檢查。
- API:
POST /api/bots/{botID}/reactions/test-formula,內容含formula和sample_text。 - MCP:
test_formula,欄位為bot_id、formula、sample。
回應包含 ok、result、error 和 matches;matches 在結果為空、答案會通過驗證時為 true。
公式在空情境計算:ctx、訂閱者參數及全域參數皆為空,因此 {鍵}、{user:鍵} 是空字串。只有範例文字可由 {text}、{answer} 或 {received_message} 取得。測試器不檢查 {{= }}、計算動作的短公式或決策表。