ภาพรวม

Sukson Messaging API ให้สมาชิกสร้าง บอท ไปไว้ในห้องแชทของ Sukson ได้ โค้ดของบอททำงานบนเซิร์ฟเวอร์ของคุณเอง ไม่ได้ทำงานบน Sukson

คำที่จะเจอบ่อยในเอกสารนี้:

• event คือข้อมูลที่ Sukson ส่งไปบอกบอทว่ามีอะไรเกิดขึ้น เช่น มีคนพิมพ์ข้อความเรียกบอท
• webhook คือ URL บนเซิร์ฟเวอร์ของคุณ ที่ Sukson ส่ง event ไปหา
• API คือ URL ของ Sukson ที่บอทเรียกเพื่อส่งข้อความหรือดูข้อมูล เช่น https://api.sukson.dev/v1/me

1. มีคนพิมพ์ข้อความที่ เรียกบอท ในห้องที่บอทอยู่
2. Sukson ส่งข้อความนั้นเป็น JSON ด้วย POST ไปที่ webhook ของบอท พร้อมลายเซ็น HMAC (ไว้ตรวจว่ามาจาก Sukson จริง) และ reply_token (ไว้ตอบกลับ)
3. เซิร์ฟเวอร์ของคุณตอบได้สองแบบ
   • ตอบ HTTP 200 พร้อม {"reply": "..."} ภายใน 10 วินาที (ตอบกลับทันที)
   • หรือตอบ 200 ไปก่อน แล้วค่อยเรียก POST /v1/chats/{chat_id}/messages ทีหลัง
4. ข้อความของบอทขึ้นในห้องทันที เหมือนข้อความของสมาชิกทั่วไป

ข้อความแบบไหนถึงบอท

trigger	เมื่อไร
mention	ข้อความที่มี @handle ของบอท
reply	ข้อความที่ตอบกลับข้อความของบอท
command	ข้อความที่ขึ้นต้นด้วย /คำสั่ง ที่บอทประกาศไว้ (หรือ /คำสั่ง@handle)
all	ทุกข้อความ เฉพาะเมื่อเจ้าของห้องเปิด “เห็นทุกข้อความ” และแพ็กเกจของบอทรองรับ

ข้อความที่ถูกแก้ไข ข้อความที่ส่งต่อมา ข้อความระบบ และข้อความจากบอท (รวมถึงบอทตัวอื่น) จะไม่ถูกส่งไปที่บอท บอทจึงไม่ตอบกันเองวนไปไม่จบ

หลักการออกแบบ API

• ที่อยู่เดียว ทุกคำขอไปที่ https://api.sukson.dev และทุก path ขึ้นต้นด้วยเวอร์ชัน เช่น /v1/me (เวอร์ชันของ API)
• path บอกความหมายในตัว me คือบอทเจ้าของ token, /v1/me/chats คือห้องที่บอทอยู่, /v1/chats/{chat_id}/messages คือข้อความในห้องนั้น
• JSON ทั้งหมด ถ้าสำเร็จ คำตอบคือข้อมูลนั้นเลย ถ้าผิดพลาด คำตอบมีรูปแบบ {message, code, details} เสมอ (ข้อผิดพลาด)
• เรียกจากเซิร์ฟเวอร์เท่านั้น API นี้ไม่เปิด CORS ห้ามเรียกจากเบราว์เซอร์ เพราะ token จะรั่ว

สิ่งที่บอทไม่ได้รับ

• ประวัติข้อความ บอทเห็นเฉพาะ event ที่ส่งมาถึงตัวเอง ไม่มี endpoint สำหรับอ่านประวัติ
• ตัวตนจริงของผู้ส่ง ไม่มีอีเมล IP โปรไฟล์ หรือ id บัญชีจริง บอทได้แค่ชื่อที่แสดง กับรหัสแทนตัวที่ใช้ได้เฉพาะบอทนั้น
• ไฟล์หรือ URL ของรูป ใน v1 บอทรู้แค่ว่าเป็นข้อความชนิดไหน (ชนิดข้อความ)
• ข้อความในห้องอื่น และข้อความที่ไม่ได้เรียกบอท (ยกเว้นห้องที่เปิด “เห็นทุกข้อความ”)

ข้อมูลส่วนบุคคล

ข้อมูลที่บอทได้รับเป็นข้อมูลส่วนบุคคลของสมาชิก เก็บเท่าที่จำเป็น ลบทิ้งเมื่อไม่ใช้แล้ว และห้ามขายหรือส่งต่อ ตามเงื่อนไขที่คุณยอมรับตอนสร้างบอท