สร้างบอทแชทตอบลูกค้า

บอทคืออะไร ใช้ทำอะไรได้

บอทคือ "บัญชีผู้ใช้" อีกแบบหนึ่งในระบบของ Korat ที่ไม่มีคนนั่งพิมพ์อยู่หลังจอ — โปรแกรมของคุณเองยิงคำขอเข้ามา แล้วข้อความจะไปโผล่ในห้องแชทที่บอทถูกเชิญไว้ ใช้ได้จริงเช่น:

• แจ้งเตือนออเดอร์ใหม่เข้าแชท — ระบบขายของร้านคุณมีออเดอร์ใหม่ ⇒ ให้บอทพิมพ์แจ้งเข้าห้องแชทกับลูกค้าหรือห้องทีมงานทันที
• แจ้งของใกล้หมด — สต๊อกเหลือน้อยกว่าที่ตั้งไว้ ⇒ บอทพิมพ์เตือนเข้าห้องทีมงานของร้าน
• แจ้งสถานะเซิร์ฟเวอร์/ระบบ — สคริปต์ตรวจสุขภาพระบบของคุณเองรันเสร็จ ⇒ ให้บอทรายงานผลเข้าห้องกลุ่มที่ทีมไอทีดูอยู่

บอททำอะไรไม่ได้บ้าง (ข้อมูลจริงจากฐานข้อมูล ไม่ใช่ข้อจำกัดชั่วคราว):

• บอทอ่านข้อความในห้องไม่ได้ — เป็นขาออกอย่างเดียว ยกเว้นถ้าคุณตั้งเว็บฮุครับข้อความเข้าไว้เอง (ดูหัวข้ออ้างอิงเทคนิคท้ายหน้า) และแม้ตั้งเว็บฮุคไว้ วันนี้ยังไม่มีอะไรถูกส่งจริง เพราะนาฬิกาที่ต้องดึงคิวไปยิงยังไม่ได้ตั้งค่าบนโปรดักชัน
• บอทเชิญตัวเองเข้าห้องไม่ได้ — ต้องมีคนที่อยู่ในห้องนั้นแล้ว (หรือมีสิทธิ์จัดการห้องนั้น) เป็นคนเชิญเสมอ
• บอทหนึ่งตัวถือโทเคนที่ใช้ได้พร้อมกันได้ไม่เกิน 2 ใบ และหนึ่งบัญชีสร้างบอทได้สูงสุด 5 ตัว

เริ่มยังไง — 4 ขั้น

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 ด้วยเลขห้องที่เชิญบอทไว้ (ดูเลขห้องได้จากลิงก์แชทในแอป หรือจากรายการห้องในจอ "บอทของฉัน")

แบบไม่เขียนโค้ด (Google Apps Script)

ถ้าไม่มีเซิร์ฟเวอร์ของตัวเอง ใช้ Google Apps Script ได้ฟรีด้วยบัญชี Google เดียว — เข้า script.google.com → โปรเจกต์ใหม่ → วางโค้ดนี้ → กด "เรียกใช้งาน" ครั้งแรกจะขอสิทธิ์เข้าถึงอินเทอร์เน็ต (อนุญาตได้ ปลอดภัย เพราะเป็นสคริปต์ของคุณเอง):

function sendKoratMessage() {
  var url = "https://koratland.com/api/bot/send";
  var payload = {
    kind: "chat",
    chat_id: 9931,              // แทนด้วยเลขห้องของคุณ
    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 ที่บันทึกออเดอร์ ใช้ตัวจับเวลา (Triggers) ของ Apps Script ตั้งให้เรียกฟังก์ชันนี้เมื่อชีตถูกแก้ไข (onEdit) หรือทุกกี่นาทีก็ได้

วิธีเดียวกันนี้ใช้ได้กับเครื่องมือ automation ที่มี action "HTTP request"/"Webhook" อยู่แล้ว เช่น n8n, Make หรือ Zapier — ตั้งค่าเป็น POST ไปที่ URL เดียวกัน ใส่หัวคำขอ X-Bot-Token และบอดี้ JSON แบบเดียวกับตัวอย่างข้างบน

ปัญหาที่เจอบ่อย

ดูรหัสผิดพลาดครบทุกตัวได้ในตารางอ้างอิงเทคนิคด้านล่าง

ส่วนอ้างอิงเทคนิค (สำหรับนักพัฒนา)

หัวข้อด้านล่างนี้เขียนสำหรับคนที่จะเขียนโปรแกรมเรียก Bot API เอง — รายละเอียดพารามิเตอร์ทุกตัว ตารางรหัสผิดพลาดครบ และเว็บฮุครับข้อความเข้า

ทำขั้น 1–3 ผ่าน RPC ตรง ๆ (ไม่ผ่านแอป)

ถ้าแอปรุ่นที่คุณใช้ยังไม่มีจอ "บอทของฉัน" หรืออยากทำแบบอัตโนมัติ เรียก RPC ของ Supabase ตรง ๆ ด้วย Access Token ของผู้ใช้ที่ล็อกอินอยู่ (ไม่ใช่โทเคนบอท) ผ่าน PostgREST — สามขั้นตอน:

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 เสมอ (regex ^[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 }'

2ก. เชิญบอทเข้าห้องกลุ่ม / ห้องทีมงาน — สิทธิ์เข้มกว่าห้องแชท

ส่ง p_kind: "community_room" หรือ "business_room" พร้อม p_target เป็น community_rooms.id/business_rooms.id ได้จริงแล้ว — แต่ผู้เชิญต้องผ่านด่านสิทธิ์ที่ตรงความหมายของห้องนั้น ไม่ใช่แค่เป็นสมาชิก:

• ห้องกลุ่ม — ผู้เชิญต้องพิมพ์ในห้องนั้นได้จริงตามกติกาของห้องเอง (read_role/post_role) ห้องคุยธรรมดาสมาชิกเชิญได้ ห้องประกาศ/ห้องหลังบ้านที่ตั้งไว้เฉพาะแอดมินต้องเป็นเจ้าของ/แอดมินกลุ่มเท่านั้น
• ห้องทีมงานร้าน — ต้องผ่านด่านของห้องเดิมครบ (สิทธิ์อ่าน/สิทธิ์โพสต์/กฎผู้รับ) บวก capability teamroom.manage เสมอ — พาบอทเข้าห้องภายในของบริษัทถือเป็น "จัดการห้อง" ไม่ใช่แค่ "พิมพ์ในห้อง"

ทั้งสองแบบยังต้องเป็นผู้จัดการบอทตัวนั้น (can_manage_bot) ด้วยเสมอ — ห้องส่วนรวมไม่ใช่ที่ที่ใครก็ลากบอทของคนอื่นเข้ามาพูดได้

ส่งข้อความ — POST /api/bot/send

ส่งโทเคนได้สองแบบ เลือกอย่างใดอย่างหนึ่ง:

# แบบที่ 1 — 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": "พัสดุออกจากร้านแล้วครับ" }'

# แบบที่ 2 — 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 (120 คำขอ/นาที ที่ตัว Worker เอง) กับ ต่อบอท (ค่าเริ่มต้น 20/นาที และ 1000/วัน ต่อบอทหนึ่งตัว ปรับได้รายตัวโดยแอดมิน) ทั้งสองแบบตอบ 429 พร้อมหัว Retry-After เป็นวินาที (ต่อ IP = 60 เสมอ · ต่อบอทต่อนาที = 60 · ต่อบอทต่อวัน = 3600)

รับข้อความเข้า — เว็บฮุค

เมื่อมีคนพิมพ์ข้อความเข้าห้องแชทที่บอทถูกเชิญไว้แล้ว (และผู้ส่งไม่ใช่บัญชีของบอทเอง — กันข้อความของบอทสะท้อนกลับหาตัวเอง) Korat จะยิง POST ไปที่ URL ที่ตั้งไว้ ต้องตั้งค่าผ่าน RPC ด้วยบัญชีผู้ใช้ที่ล็อกอินอยู่และมีสิทธิ์จัดการบอทตัวนั้น (can_manage_bot) เหมือนขั้นตอนขอโทเคน:

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:// เท่านั้น และห้ามเป็นโฮสต์ภายใน/loopback/link-local (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 รวม endpoint ข้อมูลเมทาของคลาวด์ทุกเจ้า) — ปฏิเสธตั้งแต่ตอนตั้งค่า และตรวจซ้ำอีกครั้งด้วยการ resolve 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": "สมชาย พ." }
}

เท่านี้เอง — ไม่มีเบอร์โทร อีเมล หรือโทเคนของใครทั้งสิ้น ในบอดี้ บอทเห็นแค่ห้อง/ข้อความ/ตัวตนของผู้ส่งเท่าที่จำเป็นต่อการตอบ

ตรวจลายเซ็นก่อนเชื่อคำขอ

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; // กัน replay: อายุต้องไม่เกิน 5 นาที
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

ตอบ 2xx ภายใน 8 วินาทีถือว่าส่งสำเร็จ — ตอบอย่างอื่น (รวม redirect 3xx ซึ่ง Korat ไม่ตามให้) หรือไม่ตอบเลยถือว่าล้มเหลวและเข้าคิวลองใหม่

ลองใหม่เมื่อปลายทางล่ม

ล้มเหลว ⇒ ถอยแบบทวีคูณ (1, 2, 4, 8, 16, 32, 64, 128 นาที) สูงสุด 8 ครั้งต่อข้อความ แล้วเลิกส่งข้อความนั้น ถ้าปลายทางล้มเหลวติดกัน 15 ครั้ง (ข้ามหลายข้อความ) เว็บฮุคจะถูกปิดเองอัตโนมัติ พร้อมแจ้งเตือนเจ้าของบอทในแอป — ไม่มีวันยิงตลอดกาลใส่ปลายทางที่ตายแล้ว เรียก bot_enable_webhook เปิดใหม่ได้หลังแก้ปัญหาที่ปลายทาง

ตารางรหัสผิดพลาดทั้งหมด

ทุกคำตอบมี {"ok": false, "reason": "…"} เสมอเมื่อไม่สำเร็จ — reason คือคำที่ต้องใช้ตัดสินใจ ไม่ใช่แค่ HTTP status

คำตอบเมื่อสำเร็จ

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

duplicate: true แปลว่าคำขอนี้ถูกส่งไปแล้วก่อนหน้า (กันซ้ำด้วย client_key/Idempotency-Key) — ไม่มีข้อความใหม่ถูกสร้าง แต่ยังถือเป็นความสำเร็จ (200) เพราะผลลัพธ์ที่ผู้เรียกต้องการเกิดขึ้นแล้วจริง