ภาพรวม API

ทุกเอนด์พอยต์ REST ของ RolChat ใช้ข้อตกลงเดียวกัน: Base URL เดียวกัน โครงสร้างการตอบกลับเดียวกัน การแบ่งหน้าเดียวกัน และรูปแบบข้อผิดพลาดเดียวกัน เรียนรู้ครั้งเดียว แล้วทุกกลุ่มเอนด์พอยต์ในเอกสารอ้างอิงเอนด์พอยต์ก็อ่านได้แบบเดียวกัน

Base URL และเวอร์ชัน

https://api.rolchat.com/api/v1/

เวอร์ชันอยู่ในพาธ การเพิ่มฟิลด์ที่ไม่บังคับ เอนด์พอยต์ใหม่ หรือพารามิเตอร์คิวรีใหม่ที่มีค่าเริ่มต้นไม่ถือเป็นการเปลี่ยนแปลงที่ทำให้ใช้งานไม่ได้และไม่เพิ่มเวอร์ชัน การเปลี่ยนแปลงที่ทำให้ใช้งานไม่ได้จะออกเป็น v2 และเอนด์พอยต์ v1 ที่ประกาศเลิกใช้งานยังทำงานต่ออย่างน้อยหกเดือนหลังประกาศ (ดูการเลิกใช้งาน)

การยืนยันตัวตน

วิธี	เฮดเดอร์	ใช้สำหรับ
JWT bearer	Authorization: Bearer <access_token>	เซสชันแบบโต้ตอบ (เว็บแอป แอปมือถือ)
คีย์ API	Authorization: Bearer rcp_<secret>	การเรียกระหว่างเครื่อง คีย์ API ของปลั๊กอิน
ลายมือชื่อ HMAC	X-RolChat-Signature: sha256=…	เว็บฮุกขาเข้าจากระบบของคุณ ดูเว็บฮุก
ไม่มี	-	เอนด์พอยต์สาธารณะของวิดเจ็ต (/widget/… /forms/…) จำกัดขอบเขตตามไซต์และต้นทาง

สำหรับการเชื่อมต่อ ให้ใช้คีย์ API (โทเค็นการเข้าถึงส่วนบุคคล) คีย์สร้างใน การตั้งค่า → ปลั๊กอิน → คีย์ API ของ RolChat แสดงเพียงครั้งเดียว และจัดเก็บเป็นแฮชเท่านั้น คีย์ทำได้ไม่เกินสมาชิกที่สร้างคีย์: ขอบเขตของคีย์ถูกตรวจสอบกับสิทธิ์ปัจจุบันของสมาชิกคนนั้นในทุกการเรียก ดูการยืนยันตัวตนสำหรับอายุของ JWT เฮดเดอร์ X-Account-Id และเซสชันหลายบริษัท

โครงสร้างการตอบกลับ

ทรัพยากรเดียว:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

รายการ:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

การตอบกลับที่ไม่มีเนื้อหา (204 No Content หลังการลบ) ยังคงมีเฮดเดอร์ X-Request-Id

ข้อผิดพลาด:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code เป็น snake_case ที่เครื่องอ่านได้ และเป็นค่าที่ใช้แยกเงื่อนไข message เป็นภาษาอังกฤษและมีไว้สำหรับบันทึก field และ details มีเมื่อเป็นประโยชน์และไม่มีข้อมูลส่วนบุคคล API ไม่เคยตอบ 200 พร้อมอาร์เรย์ errors: หากมีข้อผิดพลาด สถานะจะเป็น 400 ขึ้นไป รายการรหัสทั้งหมดอยู่ในหน้าข้อผิดพลาด

การแบ่งหน้า

เอนด์พอยต์รายการที่อาจเติบโตใช้การแบ่งหน้าด้วยเคอร์เซอร์ ขอหน้าแรกโดยไม่มีเคอร์เซอร์ แล้วส่ง next_cursor ที่ได้รับกลับไปตามเดิมทุกตัวอักษร:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• limit มีค่าเริ่มต้น 50 และสูงสุด 200 ค่าที่มากกว่านั้นถูกปฏิเสธด้วย 400 validation_failed
• เคอร์เซอร์เป็นค่าทึบและหมดอายุหลัง 24 ชั่วโมง (400 validation_failed พร้อม code: cursor_expired)
• ผลลัพธ์สอดคล้องกับสแนปช็อตที่ถ่ายไว้ในหน้าแรก: ระเบียนที่ถูกลบระหว่างหน้าจะหายไป ระเบียนใหม่จะปรากฏเมื่อเริ่มใหม่โดยไม่มีเคอร์เซอร์เท่านั้น
• มีการส่งเฮดเดอร์ Link พร้อม rel="next" และ rel="prev" ด้วยสำหรับไคลเอนต์ที่ต้องการ

การป้องกันคำขอซ้ำ (idempotency)

ส่งเฮดเดอร์ Idempotency-Key (UUID หรือ ULID ยาวไม่เกิน 255 ตัวอักษร) กับ POST PATCH หรือ DELETE ใดก็ได้:

• คำขอแรกที่มีคีย์จะทำงาน และสถานะกับเนื้อหาการตอบกลับจะถูกเก็บไว้ 24 ชั่วโมง
• คำขอซ้ำที่มีคีย์เดียวกันและเนื้อหาเดียวกันจะได้การตอบกลับที่เก็บไว้โดยไม่ทำผลข้างเคียงซ้ำ
• คำขอซ้ำที่มีคีย์เดียวกันแต่เนื้อหาต่างกันจะถูกปฏิเสธด้วย 409 idempotency_key_conflict

ใช้กับทุกการเรียกที่สร้างสิ่งที่มีผลข้างเคียง: การส่งข้อความ อีเมล หรือ SMS การโทรออก หรืออะไรก็ตามที่มีการเรียกเก็บเงิน คำขอ GET เป็น idempotent เสมอและไม่สนใจเฮดเดอร์นี้

ขีดจำกัดอัตรา

ขีดจำกัดนับต่อนาทีและผูกกับบัญชี คีย์ API หรือผู้ใช้ (กับที่อยู่ IP ในเส้นทางที่ไม่ต้องลงชื่อเข้าใช้) เพดานเริ่มต้น:

ถัง	ขีดจำกัดเริ่มต้น	ต่อนาที
คำขอที่ไม่ลงชื่อเข้าใช้ (ตาม IP)	60	ต่อ IP
ผู้ใช้ที่ลงชื่อเข้าใช้ (แดชบอร์ด)	1 000	ต่อผู้ใช้
คีย์ API	1 000	ต่อคีย์
เอนด์พอยต์สาธารณะของวิดเจ็ต	60 ต่อผู้เยี่ยมชม และ 600 ต่อที่อยู่เครือข่าย	ต่อนาที
การลงชื่อเข้าใช้ (/auth/login)	5	ต่อ IP
เว็บฮุกขาเข้า	300	ต่อนาที
เซิร์ฟเวอร์ MCP	600	ต่อนาที
เอนด์พอยต์ OAuth	600	ต่อนาที

เพดานเหล่านี้เป็นค่าเริ่มต้นของแพลตฟอร์มและผู้ดำเนินการเปลี่ยนได้ แผนของคุณไม่ได้คูณค่าเหล่านี้ และขีดจำกัดระดับ Enterprise ตกลงกันในสัญญา เอนด์พอยต์ที่มีขีดจำกัดจะส่งกลับ:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

เมื่อเกินขีดจำกัด การตอบกลับคือ 429 พร้อม code: rate_limited ในอาร์เรย์ errors และเฮดเดอร์ Retry-After เป็นวินาที ให้รอตามเวลานั้นก่อนเรียกครั้งต่อไป การลงชื่อเข้าใช้ล้มเหลวสิบครั้งจะล็อกบัญชี 30 นาที

ขนาดและการหมดเวลา

หมวดหมู่	ขนาดคำขอสูงสุด	การหมดเวลาของเซิร์ฟเวอร์
ค่าเริ่มต้น	1 MB	30 วินาที
ข้อความพร้อมไฟล์แนบ	25 MB	30 วินาที
นำเข้า CSV	50 MB	ส่งกลับ 202 และทำงานเบื้องหลัง
รูปภาพฐานความรู้	10 MB	30 วินาที
Bulk API	10 MB	30 วินาที
การค้นหา	1 MB	10 วินาที
คำขอ AI	1 MB	60 วินาที
เอนด์พอยต์ของวิดเจ็ต	100 KB	30 วินาที

เนื้อหาที่ใหญ่เกินจะได้ 413 payload_too_large บริการต้นทางที่หมดเวลาจะตอบ 504 พร้อม code: upstream_timeout และคำแนะนำ retry_after เมื่อการลองใหม่อาจช่วยได้

ประเภทเนื้อหา วันที่ และ ID

• คำขอและการตอบกลับเป็น application/json; charset=utf-8 การอัปโหลดไฟล์ใช้ multipart/form-data การส่งออก CSV ส่งกลับ text/csv UTF-8 ที่ไม่ถูกต้องถูกปฏิเสธด้วย 400 validation_failed
• การประทับเวลาเป็น ISO-8601 ใน UTC ละเอียดถึงมิลลิวินาที: 2026-04-20T14:23:45.123Z ข้อมูลขาเข้ารับค่าออฟเซ็ต ISO-8601 ใดก็ได้และแปลงเป็น UTC
• ตัวระบุเป็น ULID หรือ UUID แบบทึบ ไม่มี ID ที่เป็นตัวเลข และที่อยู่อีเมลหรือเบอร์โทรไม่ปรากฏใน URL

การแยกผู้เช่าและสิทธิ์

ทุกคำขอที่ยืนยันตัวตนแล้วทำงานภายในบัญชีเดียว ทรัพยากรที่เป็นของบัญชีอื่น หรือของไซต์ที่บทบาทของผู้เรียกไม่ครอบคลุม จะตอบ 404 not_found แทน 403 เพื่อไม่ให้รู้ว่าระเบียนมีอยู่ โทเค็นที่ถูกต้องแต่ไม่มีสิทธิ์ที่ต้องใช้ (เช่น contacts.delete) จะตอบ 403 forbidden สิทธิ์บางรายการมีคำต่อท้ายขอบเขต (conversations.read:own :team :all) ที่จำกัดสิ่งที่รายการส่งกลับ

PATCH รับเฉพาะฟิลด์ที่เขียนได้ id account_id created_at updated_at และฟิลด์สถานะอย่าง resolved_at เป็นแบบอ่านอย่างเดียว การส่งฟิลด์เหล่านี้จะได้ 400 validation_failed พร้อม details.forbidden_fields การเปลี่ยนสถานะทำผ่านการกระทำเฉพาะ เช่น POST /tickets/:id/resolve

ทุกการเขียนถูกบันทึกในบันทึกการตรวจสอบของบัญชี

เฮดเดอร์สำหรับการสังเกตการณ์

ทุกการตอบกลับมี:

X-Request-Id: req_01HK…

บันทึก X-Request-Id ไว้ นี่คือสิ่งแรกที่ซัพพอร์ตจะขอ

CORS

ต้นทางของแดชบอร์ดบนเบราว์เซอร์คือ https://app.rolchat.com เอนด์พอยต์สาธารณะของวิดเจ็ตอนุญาตทุกต้นทาง หรือเฉพาะต้นทางที่คุณยืนยันสำหรับไซต์ การเรียกระหว่างเซิร์ฟเวอร์ด้วยคีย์ API ไม่อยู่ภายใต้ CORS

การเลิกใช้งาน

1. การเปลี่ยนแปลงจะประกาศในบันทึกการเปลี่ยนแปลง และเอนด์พอยต์ที่ได้รับผลกระทบจะเริ่มส่ง Deprecation: true และเฮดเดอร์ Sunset พร้อมวันที่นำออก
2. เอนด์พอยต์สาธารณะยังทำงานต่ออย่างน้อยหกเดือนหลังประกาศ
3. การนำออกเกิดขึ้นในเวอร์ชันหลักใหม่เท่านั้น ภายใน v1 การเปลี่ยนแปลงเป็นการเพิ่มเติมเท่านั้น

สถานะสุขภาพ

ทุกบริการมี /healthz (liveness) และ /readyz (readiness)