待回覆留言機器人
它做什麼
訂單對話是每張訂單上,訂購人與公司之間的留言串。最後一則是訂購人寫的,而且承辦還沒回覆或標記已解決,這條對話就是「待回覆」。
機器人只讀這份清單,例如每天早上把「超過 24 小時沒回的訂單」貼到內部聊天室。它不讀留言內容,也不能回覆。
事前條件
- 公司已開通「API 與自動化」模組。到後台 →「公司設定」→「方案模組」確認;未開通時請洽平台。
- 一台會長期執行機器人的主機,裝有 Node.js 22 以上。
- 一位管理員,負責下面的建立步驟。
- 一位負責人,每週用機器人帳號重新核准登入一次(見「登入的有效期」)。
建立步驟
1. 建立自訂角色
到後台 →「團隊與權限」→「角色與權限」,按「新增角色」,例如顯示名「外部機器人」。
- 權限只勾「訂單對話」底下的「檢視訂單對話與待回覆清單」。
- 「訂單資料範圍」選「全公司訂單」。
自訂角色預設「只看自己名下的訂單」。機器人帳號名下沒有訂單,不改的話清單永遠是空的。 改成全公司後,這個角色仍只能做它被勾選的事。但「檢視訂單對話」這項權限在後台也能讀對話全文;機器人用的清單不含留言內容,不代表這個角色讀不到留言。
2. 建立專用帳號
到後台 →「團隊與權限」→「員工」,按「邀請成員」,角色選上一步的「外部機器人」。用一個專門的信箱,不要和真人共用帳號。畫面會顯示一次暫時密碼。
3. 登入並綁定兩步驟驗證
用這個帳號在瀏覽器登入後台一次,照畫面綁定兩步驟驗證。驗證 App 所在的裝置,交給負責維運機器人的人保管。詳見帳號安全與稽核。
4. 在機器人主機安裝並登入 CLI
- 在主機安裝 CLI,設定公司網址,再執行登入(指令見下方收合區)。
- 畫面印出核准網址與驗證碼。
- 在已用機器人帳號登入的瀏覽器開啟網址,重新驗證身分後按「授權」。驗證後 5 分鐘內要完成授權。
登入憑證存在主機的使用者目錄,只有該使用者讀得到。不要把它寫進程式碼庫或貼到聊天室。
›安裝與登入指令
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。清單由舊到新排序,每筆含單號、訂購人姓名與最後一則客人留言時間,不含留言內容。
›指令、參數與輸出格式
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": … } 外層:
{
"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_error | CLI 判定登入已到期。重做第 4 步。 |