集合與資料

集合是您機器人的自訂資料表。您可以用來儲存申請單、訂單、對話中收集的回覆、遊戲分數、課程預約——凡是機器人從使用者收集或透過整合取得的所有資料。此功能位於左側選單：資料 → 集合。

什麼是集合

集合由欄位（描述欄位的結構）和記錄（資料列）組成。每筆記錄是該集合欄位值的集合；內部以靈活的 JSON 文件格式儲存，因此新增欄位後集合仍可正常運作。

集合名稱在同一個機器人中必須唯一，並作為反應動作中的識別碼使用（例如 leads、orders、scores）。

欄位類型

建立集合時，您可以定義欄位清單及每個欄位的類型：

  • text — 字串（姓名、email、評論）。
  • number — 數字（金額、數量、分數）。
  • bool — 是/否（true / false）。
  • datetime — 日期與時間。
  • json — 用於複雜值的巢狀物件或陣列。

類型會影響欄位在介面中的編輯方式，以及儲存時值的型別轉換。結構描述並非嚴格固定：若記錄中出現結構描述以外的欄位，它仍會被儲存並以獨立欄顯示。

建立集合

  1. 開啟資料 → 集合並點擊新增。
  2. 指定名稱（使用英文字母，不含空格——這樣在反應中更容易引用）。
  3. 點擊欄位按鈕新增所需欄位，並為每個欄位選擇類型。
  4. 視需要設定儲存規則（見下方），然後儲存。

記錄：檢視與編輯

集合卡片上有一個表格圖示按鈕——點擊後可開啟該集合的資料視窗：

  • 檢視 — 所有列以清單方式顯示，每格對應一個欄位，從最新的開始排列。
  • 新增記錄 — 依集合結構開啟表單；每個欄位依其類型編輯（bool 使用切換開關，json 使用 JSON 輸入欄位等）。
  • 編輯（鉛筆圖示）— 修改現有列。
  • 刪除（垃圾桶圖示）— 刪除列。

記錄也可由機器人反應的動作自動填入（見下方）。手動編輯與自動寫入使用同一個集合。

儲存（Retention）

為避免集合無限增長，可設定自動清理規則：

  • 最多保留記錄數 — 超過限制時，最舊的記錄將被刪除。
  • 最長保留天數 — 超過指定天數的記錄將被刪除。

清理作業由背景程序定期執行；規則可以組合使用。

從反應存取資料

集合與反應建構器直接整合。反應動作中可使用：

  • 建立記錄 — 新增一列；值取自範本（例如 {{user.id}}、{{message.text}}）。可設定去重複化鍵值，使重複呼叫時更新同一列而非建立重複項目。
  • 更新記錄 — 修改符合條件的列。
  • 查詢記錄 — 將符合條件的列讀入執行情境作為陣列，以便後續逐一處理。
  • 刪除記錄 — 依條件刪除列。
  • 迴圈（for-each） — 逐一遍歷情境中的陣列，並對每個元素執行巢狀動作（例如依集合清單群發訊息）。

這樣，機器人無需外部資料庫即可維護 CRM、累積申請單、累計積分並建立報表。

從 Mini App 存取

集合記錄可從您機器人的 Telegram Mini App 讀取：前端依名稱並附加篩選條件與限制來查詢集合資料。這樣可以直接在 Telegram 中向使用者顯示其訂單、歷史記錄或排行榜。

建議

  • 使用簡短的機器讀取欄位名稱（email、total、paid）——這樣在反應範本中更容易引用。
  • 針對等冪寫入（例如「每位使用者一份申請」），請使用去重複化鍵值。
  • 對日誌和暫時性資料啟用 retention，避免集合過度增長。
  • 當值的結構事先不固定時，適合使用 json 類型。