ดูแลห้อง (moderation)

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

สิทธิ์ของบอทในห้อง

สิทธิ์	ทำอะไรได้
delete_messages	ลบข้อความของคนอื่นในห้องนั้น
kick	เตะคนออกจากห้อง
ban	แบนและยกเลิกแบน

• บอทที่เพิ่งเข้าห้องยังไม่มีสิทธิ์ใดเลย
• เจ้าของห้องเท่านั้นที่ให้สิทธิ์ได้ โดยเปิดสวิตช์ในหน้าตั้งค่าบอทของห้องนั้นในแอปหรือเว็บ Sukson แอดมินของห้องให้สิทธิ์ไม่ได้ แต่ถอนสิทธิ์ได้
• สิทธิ์เป็นของแต่ละห้อง ได้สิทธิ์ในห้องหนึ่งไม่ได้แปลว่าได้ในห้องอื่น
• ถ้าบอทออกจากห้องแล้วถูกเพิ่มกลับเข้ามาใหม่ หรือห้องเปลี่ยนเจ้าของ สิทธิ์จะเริ่มจากศูนย์อีกครั้ง
• ดูสิทธิ์ปัจจุบันได้ที่ bot.rights ของ GET /v1/chats/{chat_id}

บอทต้องอยู่ในสถานะ active ในห้องนั้น ถ้าเจ้าของหยุดบอทไว้ จะได้ 403 FORBIDDEN เหตุผล paused เหมือนตอนส่งข้อความ

คนที่บอทแตะไม่ได้

ต่อให้มีสิทธิ์ บอททำสิ่งเหล่านี้กับคนต่อไปนี้ไม่ได้ และจะได้ 403 FORBIDDEN เหตุผล protected_member

• เจ้าของห้องและแอดมินของห้อง
• ทีมงาน Sukson
• บอททุกตัว รวมทั้งตัวบอทเอง

ลบข้อความของคนอื่น

DELETE /v1/messages/{message_id}

endpoint เดียวกับที่บอทใช้ลบข้อความของตัวเอง (ข้อความ) ถ้าเป็นข้อความของคนอื่นในห้องที่บอทอยู่ ต้องมีสิทธิ์ delete_messages

curl -s -X DELETE https://api.sukson.dev/v1/messages/812345 -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{ "message_id": 812345, "chat_id": "0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10" }

ไฟล์และรูปที่แนบมากับข้อความถูกลบไปด้วย ข้อความระบบ (เช่น “สมชายเข้าร่วมห้อง”) ลบไม่ได้

เตะออกจากห้อง

DELETE /v1/chats/{chat_id}/members/{user_id}

ต้องมีสิทธิ์ kick ไม่มี body user_id คือรหัสแทนตัวของคนนั้น

curl -s -X DELETE https://api.sukson.dev/v1/chats/0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10/members/9f2c4e7a1b3d5f60718293a4b5c6d7e8 \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{ "kicked": true }

• กลุ่มและช่อง คนนั้นถูกเอาออกจากห้อง เหมือนแอดมินเอาออก มีข้อความระบบในห้อง และบอทในห้องได้ event member_left ถ้าคนนั้นไม่ได้อยู่ในห้องแล้ว จะได้ 404 NOT_FOUND คนที่ถูกเตะกลับเข้าห้องได้ถ้ามีคนชวนใหม่
• ห้องสาธารณะ คนนั้นถูกตัดออกจากห้องทันที แต่เข้ามาใหม่ได้ ถ้าไม่อยากให้กลับมา ให้ใช้แบนแทน ใช้ได้กับผู้มาเยือนด้วย (ใช้ sender.id จาก event) การเตะไม่ทำให้หมดสถานะสมาชิก บอทจึงไม่ได้ member_left และคนนั้นยังอยู่ในรายชื่อสมาชิก คนนั้นต้องเป็นสมาชิกของห้องหรือเพิ่งส่งข้อความในห้อง ไม่อย่างนั้นจะได้ 404 NOT_FOUND

แบน

POST /v1/chats/{chat_id}/bans

ต้องมีสิทธิ์ ban

ฟิลด์	ชนิด	กติกา
user_id	string	จำเป็น รหัสแทนตัวของคนนั้น (hex ตัวพิมพ์เล็ก 32 ตัว)
reason	string	ไม่บังคับ ยาวไม่เกิน 280 ตัวอักษร (อีโมจิหนึ่งตัวนับเป็น 2)
duration_minutes	integer	ไม่บังคับ 1–525,600 (หนึ่งปี) เฉพาะห้องสาธารณะ ถ้าไม่ใส่ แบนจนกว่าจะยกเลิก

curl -s -X POST https://api.sukson.dev/v1/chats/7d2e9f10-3c4b-4a5d-8e6f-1a2b3c4d5e6f/bans \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"9f2c4e7a1b3d5f60718293a4b5c6d7e8","reason":"ส่งลิงก์สแปม","duration_minutes":1440}'

{ "banned": true, "expires_at": "2026-11-08T03:15:00.000Z" }

• กลุ่มและช่อง คนนั้นถูกเอาออกจากห้อง และกลับเข้ามาด้วยลิงก์ชวนไม่ได้จนกว่าจะยกเลิกแบน แบนแบบมีกำหนดเวลาใช้ไม่ได้ ถ้าใส่ duration_minutes จะได้ 422 INVALID เหตุผล rooms_only ส่วน reason ไม่ถูกเก็บไว้
• ห้องสาธารณะ แบนตามระยะเวลาที่ใส่ หรือจนกว่าจะยกเลิก ใช้ได้กับผู้มาเยือนด้วย การแบนไม่ทำให้หมดสถานะสมาชิก บอทจึงไม่ได้ member_left และคนนั้นยังอยู่ในรายชื่อสมาชิก expires_at บอกเวลาที่แบนหมดอายุ (null คือไม่มีกำหนด)

ยกเลิกแบน

DELETE /v1/chats/{chat_id}/bans/{user_id}

ต้องมีสิทธิ์ ban ไม่มี body

{ "unbanned": true }

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

ขีดจำกัด

บอทหนึ่งตัวลบข้อความของคนอื่น เตะ แบน และยกเลิกแบน รวมกันได้ 30 ครั้งต่อนาที นับรวมทุกห้อง ถ้าเกิน จะได้ 429 RATE_LIMITED พร้อม details.retry_after (วินาที) ขีดจำกัดนี้แยกจาก rate limit ของ API ทั่วไป

ข้อผิดพลาด

HTTP	code	เมื่อไร
403	FORBIDDEN	details.reason เป็น missing_right (บอทไม่มีสิทธิ์ที่ต้องใช้ details.right บอกว่าสิทธิ์ไหน), protected_member (คนที่บอทแตะไม่ได้), system_message (ลบข้อความระบบ) หรือ paused, banned, attacher_lost_rights เหมือนตอนส่งข้อความ
403	CHAT_INACTIVE	ห้องปิดอยู่
404	NOT_FOUND	บอทไม่ได้อยู่ในห้องนี้ ไม่มีข้อความนี้ ไม่รู้จัก user_id นี้ในห้องนี้ หรือ user_id ใน path ผิดรูปแบบ
422	INVALID	user_id ใน body ผิดรูปแบบ, reason ยาวเกิน, duration_minutes อยู่นอกช่วง หรือ rooms_only
429	RATE_LIMITED	ดูแลห้องเร็วเกินไป ดู details.retry_after

{ "message": "The chat's owner hasn't given this bot this right here", "code": "FORBIDDEN", "details": { "reason": "missing_right", "right": "kick" } }