toko

待回覆留言機器人

外部日報機器人用一個專用後台帳號,定期列出客人留言後還沒有人處理的訂單,提醒承辦回覆。

它做什麼

訂單對話是每張訂單上,訂購人與公司之間的留言串。最後一則是訂購人寫的,而且承辦還沒回覆或標記已解決,這條對話就是「待回覆」。

機器人只讀這份清單,例如每天早上把「超過 24 小時沒回的訂單」貼到內部聊天室。它不讀留言內容,也不能回覆。

事前條件

  • 公司已開通「API 與自動化」模組。到後台 →「公司設定」→「方案模組」確認;未開通時請洽平台。
  • 一台會長期執行機器人的主機,裝有 Node.js 22 以上。
  • 一位管理員,負責下面的建立步驟。
  • 一位負責人,每週用機器人帳號重新核准登入一次(見「登入的有效期」)。

建立步驟

1. 建立自訂角色

到後台 →「團隊與權限」→「角色與權限」,按「新增角色」,例如顯示名「外部機器人」。

  • 權限只勾「訂單對話」底下的「檢視訂單對話與待回覆清單」。
  • 「訂單資料範圍」選「全公司訂單」。

2. 建立專用帳號

到後台 →「團隊與權限」→「員工」,按「邀請成員」,角色選上一步的「外部機器人」。用一個專門的信箱,不要和真人共用帳號。畫面會顯示一次暫時密碼。

3. 登入並綁定兩步驟驗證

用這個帳號在瀏覽器登入後台一次,照畫面綁定兩步驟驗證。驗證 App 所在的裝置,交給負責維運機器人的人保管。詳見帳號安全與稽核。

4. 在機器人主機安裝並登入 CLI

  1. 在主機安裝 CLI,設定公司網址,再執行登入(指令見下方收合區)。
  2. 畫面印出核准網址與驗證碼。
  3. 在已用機器人帳號登入的瀏覽器開啟網址,重新驗證身分後按「授權」。驗證後 5 分鐘內要完成授權。

登入憑證存在主機的使用者目錄,只有該使用者讀得到。不要把它寫進程式碼庫或貼到聊天室。

›安裝與登入指令
sh
npm i -g @toko-cloud/cli
toko target add prod https://your-tenant.example.com --production
toko login --no-browser

憑證存在 ~/.toko/config.json(權限 0600)。

5. 讀取待回覆清單

機器人用 CLI 讀取清單,指定「最後一則客人留言距今至少幾小時」,例如 24。清單由舊到新排序,每筆含單號、訂購人姓名與最後一則客人留言時間,不含留言內容。

›指令、參數與輸出格式
sh
toko order-conversations awaiting-reply --older-than-hours 24 --json
  • --older-than-hours 必填,整數 1–720。
  • --page、--page-size(上限 200)分頁。
  • 對應 API:GET /order-conversations/awaiting-reply,需要 order_conversation.read。見 CLI 參考與 API 參考。

--json 印出 API 的 data 本體,CLI 已拆掉 { "ok": true, "data": … } 外層:

json
{
  "rows": [
    {
      "orderId": "ord_…",
      "orderNumber": "W26101400042",
      "customerName": "陳怡君",
      "lastCustomerMessageAt": "2026-10-12T13:40:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50
}

失敗時 stdout 沒有輸出,stderr 印 { "ok": false, "error": { "code", "message", "issues" } }。issues 是 [{ "path", "message" }],只有驗證錯誤時才有內容。

exit code:成功是 0,伺服器錯誤(5xx)是 2,其他錯誤是 1。機器人先看 exit code,再解析 stderr 的 error.code。

登入的有效期

CLI 登入不是永久金鑰,有效期 7 天,從核准當下起算。每天呼叫不會延長它。

  • 排程在 7 天內重做第 4 步(建議每 5–6 天一次)。核准要有人用機器人帳號登入後台並通過兩步驟驗證,請預先排定負責人。
  • 到期後 CLI 不送出請求,直接在本機失敗。機器人的告警要涵蓋這種失敗(見「常見問題」)。
  • 要立即收回存取權,凍結這個帳號、改它的角色,或到「公司設定」→「開發者」→「CLI 登入」撤銷。

常見問題

最常見的問題是清單永遠是空的:角色的訂單資料範圍還是「只看自己名下的訂單」,改成「全公司訂單」即可。其他錯誤依錯誤碼處理。

›錯誤碼與處理
狀況原因與處理
成功但清單永遠是空角色的訂單資料範圍還是「只看自己名下的訂單」,改成「全公司訂單」。
回 403 forbidden角色沒有勾「檢視訂單對話與待回覆清單」。
回 403 module_disabled公司沒有開通「API 與自動化」模組。
回 422 validation小時數缺少、不是整數或超出 1–720。
回 401帳號被凍結,或登入被撤銷。重做第 4 步。
失敗且錯誤碼是 cli_errorCLI 判定登入已到期。重做第 4 步。

Command Palette

Search for a command to run...