做一個回客人訊息的聊天機器人

機器人是什麼，能拿來做什麼

機器人是 Korat 系統裡另一種“使用者帳號”，螢幕後面沒有人在打字——是你自己的程式發請求進來，訊息就出現在機器人被邀請進去的會話裡。實際用法比如：

• 把新訂單提醒發進會話——你自己的銷售系統來了新單 ⇒ 讓機器人立刻發進和客人的會話或團隊的房間。
• 庫存告急提醒——庫存低於你設的線 ⇒ 機器人發進店鋪的團隊房間。
• 伺服器／系統狀態播報——你自己的健康檢查指令碼跑完 ⇒ 讓機器人把結果報進 IT 團隊盯著的群組房間。

機器人做不到的事（這是資料庫裡的真實情況，不是臨時限制）：

• 機器人讀不到房間裡的訊息——它只出不進，除非你自己配了接收訊息的 webhook（見頁尾的技術參考）。而且就算配了，今天也不會真的有東西發出來，因為把佇列取出去投遞的定時器在生產環境上還沒配置。
• 機器人不能自己把自己拉進房間——永遠要由已經在那個房間裡的人（或者有該房間管理權限的人）來邀請。
• 一個機器人同時最多持有2個有效令牌，一個帳號最多建立5個機器人。

怎麼開始——四步

1. 1建立機器人：給它起名字和使用者名稱（使用者名稱必須以 bot 結尾，比如 orderbot）——想讓它屬於店鋪（而不是隻屬於你個人），建立時選上店鋪就行。
2. 2複製令牌：建立成功時系統只顯示一次令牌——立刻複製並妥善儲存。關掉那個介面之後，真實值再也取不回來（只能重新簽發一個）。
3. 3把機器人請進房間：選你想讓它說話的會話、群組房間或團隊房間——你本人必須已經在那個房間裡（或者有該房間的管理權限）才能邀請。
4. 4發出第一條訊息：拿第2步的令牌去調 Bot API——下一節有可以照抄的例子。

示例——發出第一條訊息

只有一個端點：POST https://koratland.com/api/bot/send。把令牌放在請求頭裡，再說清楚往哪個房間說什麼：

curl 版（給熟悉終端的人）

curl -X POST "https://koratland.com/api/bot/send" \
  -H "X-Bot-Token: kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "來新訂單了" }'

把 kbot_12_xxxxxxxxxxxxxxxxxxxx 換成機器人的真實令牌，把 9931 換成你請機器人進去的那個房間的 id（房間 id 可以從應用裡的會話連結看到，或者在“我的機器人”介面的房間列表裡找）。

不寫程式碼版（Google Apps Script）

沒有自己的伺服器，用一個 Google 帳號就能免費用 Google Apps Script——開啟 script.google.com → 新建專案 → 貼上這段程式碼 → 點“執行”。第一次會申請訪問網際網路的權限（可以允許，這是你自己的指令碼，安全）：

function sendKoratMessage() {
  var url = "https://koratland.com/api/bot/send";
  var payload = {
    kind: "chat",
    chat_id: 9931,              // 換成你的房間 id
    text: "來新訂單了"            // 換成你要發的文字
  };
  var options = {
    method: "post",
    contentType: "application/json",
    headers: { "X-Bot-Token": "kbot_12_xxxxxxxxxxxxxxxxxxxx" },  // 換成你的機器人令牌
    payload: JSON.stringify(payload)
  };
  var res = UrlFetchApp.fetch(url, options);
  Logger.log(res.getContentText());  // 在“執行日誌”（Execution log）裡看結果
}

點一次“執行”就能測試——想讓它自動發，比如記錄訂單的 Google Sheet 每加一行就發一次，用 Apps Script 的觸發器（Triggers）設成表格被修改時（onEdit）呼叫這個函式，或者每隔幾分鐘調一次。

同樣的做法也適用於任何自帶 “HTTP request”／“Webhook” 動作的自動化工具，比如 n8n、Make 或 Zapier——設成 POST 到同一個 URL，加上 X-Bot-Token 請求頭，JSON 請求體和上面的例子一樣。

常見問題

完整的錯誤碼見下面技術參考裡的表格。

技術參考（給開發者）

下面這幾節寫給要自己寫程式調 Bot API 的人——每個引數的細節、完整的錯誤碼錶，以及接收訊息的 webhook。

直接用 RPC 完成第1–3步（不走應用）

你用的應用版本還沒有“我的機器人”介面，或者想自動化處理，就用已登入使用者的 Access Token（不是機器人令牌）透過 PostgREST 直接調 Supabase 的 RPC——三步：

1. 建立機器人——bot_create

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_create" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "p_name": "通知機器人",
    "p_username": "notifybot",
    "p_business_id": null,
    "p_about": "播報訂單狀態"
  }'

p_username 只能用 a–z 0–9 _，長度 4–31，並且必須以 bot 結尾（正則 ^[a-z][a-z0-9_]{2,29}bot$）。想讓機器人屬於店鋪就傳 p_business_id——呼叫者必須是該店鋪成員並持有 bot.manage 權限。成功響應裡的 token 是這個令牌一生中唯一一次出現的真實值，資料庫只存 sha256 雜湊——錯過了就只能重新簽發（bot_rotate_token），沒有任何辦法把真實值讀回來。

{ "ok": true, "bot_id": 12, "user_id": 4821, "username": "notifybot", "token": "kbot_12_…" }

2. 把機器人請進會話——bot_invite

你必須確實在那個房間裡（或者房間是店鋪收件箱時，你是店鋪員工），並且能管理這個機器人（can_manage_bot）。p_target 就是 chats.id。

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_invite" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "p_bot": 12, "p_kind": "chat", "p_target": 9931 }'

2a. 請進群組房間／團隊房間——權限比普通會話嚴

傳 p_kind: "community_room" 或 "business_room"，p_target 傳 community_rooms.id／business_rooms.id，這已經可以用了——但邀請人必須過得了與那個房間含義相符的權限關，光是成員不夠：

• 群組房間——邀請人必須按房間自己的規則（read_role／post_role）真的能在那裡發言。普通聊天房間成員就能邀請；設成只有管理員能發的公告房或後臺房，只有群主／管理員才行。
• 店鋪團隊房間——房間原有的各道關（讀權限／發帖權限／收件人規則）都要過，再加上 teamroom.manage 這項能力——把機器人帶進公司內部房間算“管理房間”，不只是“在房間裡發言”。

兩種情況都仍然要求你是這個機器人的管理者（can_manage_bot）——公共房間不是誰都能把別人的機器人拖進來說話的地方。

傳送訊息——POST /api/bot/send

令牌有兩種傳法，任選其一：

# 方式一 —— Authorization: Bearer
curl -X POST "https://koratland.com/api/bot/send" \
  -H "Authorization: Bearer kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-9931-shipped" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "包裹已經從店裡發出" }'

# 方式二 —— X-Bot-Token
curl -X POST "https://koratland.com/api/bot/send" \
  -H "X-Bot-Token: kbot_12_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "chat", "chat_id": 9931, "text": "包裹已經從店裡發出" }'

完全不傳令牌會得到 401：

{ "ok": false, "reason": "bad_token", "detail": "令牌只能放在 Authorization: Bearer … 或 X-Bot-Token 裡" }

請求體欄位

私聊 vs 店鋪收件箱——由哪個欄位決定

kind決定的是目標屬於哪張表（會話／群組房間／店鋪團隊房間）。而私聊和店鋪收件箱並不是靠 kind 區分的——它們都是 chats 表裡的行，區別只在 chats.business_id 有沒有值（有值 = 店鋪收件箱）。邀請權限檢查、使用者拉黑檢查，以及“店家不能先開口（conversation_not_open）”這條規則，讀的都是這一列——你傳的 chat_id 本來就必須是正確的那個房間，API 裡沒有單獨的“私聊／商用”引數可選。

Idempotency-Key 與速率上限

用標準請求頭 Idempotency-Key，或者請求體裡的 client_key——任選其一。兩個都傳時值必須一致，不一致會得到 422 idempotency_key_conflict。用同一個鍵（同房間＋同鍵）重發同一個請求，會拿回原來的 200 響應並帶 "duplicate": true，不會產生重複訊息。

上限分兩層：按 IP（Worker 自身 120 請求/分鐘）和按機器人（預設每個機器人 20/分鐘、1000/天，管理員可逐個調整）。兩種都返回 429 並帶 Retry-After 請求頭，單位為秒（按 IP 恆為 60 · 按機器人每分鐘 = 60 · 按機器人每天 = 3600）。

接收訊息——webhook

當有人在機器人已被邀請進去的會話裡發訊息（且傳送者不是機器人自己的帳號——防止機器人的訊息回彈給自己），Korat 會向你設定的 URL 發一個 POST。設定要用已登入、且能管理這個機器人（can_manage_bot）的使用者帳號透過 RPC 完成，和申請令牌那一步一樣：

curl -X POST "https://<SUPABASE_PROJECT>.supabase.co/rest/v1/rpc/bot_set_webhook" \
  -H "apikey: <SUPABASE_ANON_KEY>" \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "p_bot": 12, "p_url": "https://your-server.example.com/korat-webhook" }'

{ "ok": true, "secret": "a1b2c3…", "note": "這個 secret 只顯示一次——自己儲存好用來校驗簽名" }

URL 必須是 https://，並且不能是內網／迴環／鏈路本地地址（localhost、127.0.0.1、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16，包括各家雲的後設資料端點）——設定時就拒絕，每次投遞前還會真實解析 DNS 再查一遍，防止 DNS 事後被指到別處。secret 只在設定或輪換時顯示一次——bot_rotate_webhook_secret(p_bot) 隨時可以輪換，bot_disable_webhook(p_bot)／bot_enable_webhook(p_bot) 自行關閉或開啟，bot_webhook_status(p_bot) 檢視狀態（不返回 secret）。

你的接收端會收到的請求長什麼樣

POST /korat-webhook HTTP/1.1
Content-Type: application/json
X-Korat-Signature: sha256=<hex>
X-Korat-Timestamp: 1750000000000

{
  "event": "message.created",
  "chat_id": 9931,
  "message_id": 88213,
  "text": "有紅色的嗎",
  "time": "14:02",
  "sender": { "id": 4821, "username": "somchai_p", "name": "Somchai P." }
}

就這些——請求體裡沒有任何人的電話、郵箱或令牌。機器人只看到房間、訊息，以及為了回覆所必需的那點傳送者身份資訊。

先驗籤，再相信這個請求

X-Korat-Signature 是 HMAC-SHA256(secret, "<timestamp>." + rawBody) 的十六進位制值——Node.js 示例：

const crypto = require("crypto");
function verify(rawBody, signatureHeader, timestampHeader, secret) {
  const age = Date.now() - Number(timestampHeader);
  if (!(age >= 0 && age < 5 * 60_000)) return false; // 防重放：時間戳不能超過5分鐘
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

在8秒內返回 2xx 算投遞成功——返回別的（包括 3xx 重定向，Korat 不會跟進）或者根本不回，都算失敗並排隊重試。

接收端掛了之後的重試

失敗 ⇒ 指數退避（1、2、4、8、16、32、64、128 分鐘），每條訊息最多重試 8 次，然後放棄這一條。如果接收端連續失敗15次（跨多條訊息），webhook 會自動被關閉，並在應用裡通知機器人所有者——絕不會對一個已經死掉的接收端永遠發下去。你那邊修好之後，調 bot_enable_webhook 重新開啟。

完整錯誤碼錶

失敗時每個響應都一定有 {"ok": false, "reason": "…"}——該拿來做判斷的是 reason，而不只是 HTTP 狀態碼。

成功時的響應

{ "ok": true, "duplicate": false, "message_id": 88213 }

duplicate: true 表示這個請求之前已經發過了（靠 client_key／Idempotency-Key 去重）——沒有產生新訊息，但仍算成功（200），因為呼叫方想要的結果確實已經發生了。