Open API
เรียก REST API ของ Khuivo เพื่ออ่านและแก้ ticket บทสนทนา ข้อความ และลูกค้า พร้อมวิธียืนยันตัวตน rate limit การแบ่งหน้า และตัวอย่าง curl
ในหน้านี้
Open API คือ REST API สำหรับให้ระบบของคุณอ่านและแก้ข้อมูลใน workspace เช่น ดึง ticket ที่เปิดอยู่ ส่งข้อความตอบลูกค้า หรือสร้างลูกค้าจาก ERP ต้องมี API key ก่อน
พื้นฐาน #
- Base URL:
https://api.khuivo.com/v1— ค่าจริงของ workspace คุณแสดงในแท็บ เอกสาร API ที่ ตั้งค่า → Developer กดปุ่มคัดลอกจากที่นั่นได้เลย - รับและตอบเป็น JSON (
Content-Type: application/json) - 1 key = 1 workspace ไม่ต้องส่ง workspace id
- เอกสารอ้างอิงแบบเต็ม (ทุก endpoint ทุก field) เปิดได้จากปุ่ม เปิดเอกสาร API ในแท็บเดียวกัน หรือที่
https://api.khuivo.com/_docs
เริ่มเรียก API ครั้งแรก #
- 1
สร้าง key ที่ API keys ให้สิทธิ์อ่าน Ticket อย่างน้อย
- 2
เปิดแท็บ เอกสาร API แล้วคัดลอก Base URL
- 3
ตั้งค่าตัวแปรใน terminal แล้วเรียก
/meเพื่อตรวจว่า key ใช้ได้ - 4
ลองเรียก
/ticketsตามตัวอย่างด้านล่าง
export KHUIVO_API_KEY="khv_live_***"
export BASE="https://api.khuivo.com/v1"
curl -H "x-api-key: $KHUIVO_API_KEY" "$BASE/me"การยืนยันตัวตน #
ส่ง key ในทุก request ด้วย header แบบใดแบบหนึ่ง:
x-api-key: khv_live_…Authorization: Bearer khv_live_…
Rate limit #
- 20 request ต่อวินาที (burst ได้ถึง 40) และ 100,000 request ต่อวันต่อ key
- ทุกคำตอบมี header
X-RateLimit-Limit,X-RateLimit-RemainingและX-RateLimit-Reset(เวลาแบบ unix seconds) บอกโควตารายวันที่เหลือ - เกินกำหนดจะได้ HTTP 429
API_RATE_LIMITEDพร้อม headerRetry-Afterบอกว่าต้องรอกี่วินาที
Idempotency-Key #
ส่ง header Idempotency-Key กับ POST เพื่อกันการทำซ้ำ เช่น ส่งข้อความเดิมสองครั้งเพราะเน็ตหลุดแล้ว retry
- ค่ายาวได้ไม่เกิน 255 ตัวอักษร ใช้ค่าไม่ซ้ำต่อคำขอ เช่น UUID
- ส่งค่าเดิมซ้ำภายใน 24 ชั่วโมง จะได้คำตอบเดิมกลับมาโดยไม่ทำซ้ำ
- ใช้ค่าเดิมกับคำขออื่น (method หรือ path ต่างกัน) จะได้ HTTP 409
IDEMPOTENCY_KEY_REUSED
การแบ่งหน้า #
ทุก endpoint ที่คืนรายการตอบในรูป {"items": [...], "next_cursor": "..."}
- กำหนดจำนวนต่อหน้าด้วย
pageSize(สูงสุด 100) - ขอหน้าถัดไปโดยส่ง
cursorเป็นค่าnext_cursorที่ได้จากหน้าก่อน next_cursorเป็นnullแปลว่าเป็นหน้าสุดท้ายแล้ว
Endpoints #
Path ทั้งหมดต่อจาก Base URL
| Method | Path | Scope | ใช้ทำอะไร |
|---|---|---|---|
| GET | /me | — | ข้อมูล key และ workspace |
| GET | /tickets | tickets:read | รายการ ticket กรองด้วย status, q, contact_id, assignee_id, channel_account_id |
| GET | /tickets/{id} | tickets:read | ticket หนึ่งใบ |
| PATCH | /tickets/{id} | tickets:write | แก้ subject, priority, fields |
| POST | /tickets/{id}/assign | tickets:write | มอบหมายด้วย user_id หรือ team_id |
| POST | /tickets/{id}/close | tickets:write | ปิด ticket ใส่ reason ได้ |
| POST | /tickets/{id}/reopen | tickets:write | เปิด ticket อีกครั้ง |
| GET | /tickets/{id}/notes | messages:read | โน้ตภายในของ ticket |
| POST | /tickets/{id}/notes | messages:write | เขียนโน้ตภายใน (text) |
| GET | /conversations | conversations:read | รายการบทสนทนา |
| GET | /conversations/{id} | conversations:read | บทสนทนาหนึ่งรายการ |
| POST | /conversations/{id}/read | conversations:write | ทำเครื่องหมายว่าอ่านแล้ว |
| POST | /conversations/{id}/labels | conversations:write | ติด label (label_ids) |
| DELETE | /conversations/{id}/labels/{labelId} | conversations:write | ถอด label |
| GET | /conversations/{id}/messages | messages:read | ข้อความในบทสนทนา |
| POST | /conversations/{id}/messages | messages:write | ส่งข้อความถึงลูกค้า |
| GET | /messages/search | messages:read | ค้นหาข้อความ (q) |
| GET | /contacts | contacts:read | รายชื่อลูกค้า ค้นหาด้วย q |
| POST | /contacts | contacts:write | สร้างลูกค้า |
| GET | /contacts/{id} | contacts:read | ลูกค้าหนึ่งราย |
| PATCH | /contacts/{id} | contacts:write | แก้ข้อมูลลูกค้า |
| POST | /contacts/{id}/merge | contacts:write | รวมลูกค้า source_contact_id เข้ากับรายนี้ |
| GET | /accounts | accounts:read | ช่องทางที่เชื่อมไว้ |
| GET | /users | users:read | สมาชิกใน workspace |
| GET | /teams | teams:read | ทีม |
| GET | /labels | labels:read | label |
| GET | /analytics/summary | analytics:read | สรุปรายงาน |
| GET | /analytics/events | analytics:read | event ตามช่วงเวลา (from, to, types) |
Open API ไม่มี endpoint สำหรับออเดอร์และสินค้า
ตัวอย่าง #
ดึง ticket ที่เปิดอยู่ 20 ใบแรก แล้วขอหน้าถัดไปด้วย next_cursor:
curl -H "x-api-key: $KHUIVO_API_KEY" \
"$BASE/tickets?status=open&pageSize=20"
curl -H "x-api-key: $KHUIVO_API_KEY" \
"$BASE/tickets?status=open&pageSize=20&cursor=NEXT_CURSOR"ส่งข้อความตอบลูกค้าในบทสนทนา (type เป็น text, media, template หรือ flex ข้อความยาวได้ไม่เกิน 4,096 ตัวอักษร):
curl -X POST "$BASE/conversations/CONVERSATION_ID/messages" \
-H "x-api-key: $KHUIVO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 2f6c1d3e-order-1001" \
-d '{"type":"text","text":"สวัสดีค่ะ ออเดอร์ของคุณจัดส่งแล้วนะคะ"}'ส่ง Flex Message ที่ออกแบบไว้ใน Flex Message Studio ด้วย flex_template_id (id อยู่ในที่อยู่ของหน้าแก้ไขใน Studio) และค่าตัวแปรใน variables — ช่องทางที่ไม่ใช่ LINE ได้รับข้อความแจ้งเตือนแทน สำหรับนักพัฒนา ส่ง Flex JSON เองได้ด้วย flex (bubble หรือ carousel) และ text เป็นข้อความแจ้งเตือน:
curl -X POST "$BASE/conversations/CONVERSATION_ID/messages" -H "x-api-key: $KHUIVO_API_KEY" -H "Content-Type: application/json" -d '{"type":"flex","flex_template_id":"FLEX_TEMPLATE_ID","variables":{"code":"SAVE50"}}'แก้การ์ดเฉพาะครั้งนี้ได้ด้วย flex_override — contents คือการ์ดทั้งใบที่แก้แล้ว (bubble หรือ carousel) และ/หรือ alt_text คือข้อความแจ้งเตือนใหม่ Flex Message ที่บันทึกไว้ไม่เปลี่ยน ระบบตรวจตามขีดจำกัดของ LINE (ถ้าไม่ผ่านตอบ 400 พร้อมตำแหน่งที่ผิดเป็นภาษาไทย) และใส่ค่าตัวแปรหลังนำการแก้มาใช้ จึงใช้ {customer_name} ในข้อความที่แก้ได้:
curl -X POST "$BASE/conversations/CONVERSATION_ID/messages" -H "x-api-key: $KHUIVO_API_KEY" -H "Content-Type: application/json" -d '{"type":"flex","flex_template_id":"FLEX_TEMPLATE_ID","flex_override":{"alt_text":"โปรพิเศษสำหรับ {customer_name}","contents":{"type":"bubble","body":{"type":"box","layout":"vertical","contents":[{"type":"text","text":"ลด 70% วันนี้เท่านั้น"}]}}}}'เขียนโน้ตภายในถึงทีม (ลูกค้าไม่เห็น):
curl -X POST "$BASE/tickets/TICKET_ID/notes" \
-H "x-api-key: $KHUIVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"ERP: ลูกค้ารายนี้ชำระเงินแล้ว"}'ปิด ticket:
curl -X POST "$BASE/tickets/TICKET_ID/close" \
-H "x-api-key: $KHUIVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"resolved"}'สร้างลูกค้าใหม่ (ถ้าเบอร์หรืออีเมลตรงกับลูกค้าเดิม ระบบอาจรวมให้ ดู รวมลูกค้า):
curl -X POST "$BASE/contacts" \
-H "x-api-key: $KHUIVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name":"สมชาย","phone":"0812345678","email":"[email protected]"}'เคล็ดลับ #
- ใส่
Idempotency-Keyทุกครั้งที่ส่งข้อความหรือสร้างข้อมูล เพื่อให้ retry ได้อย่างปลอดภัย - ถ้าอยากรู้ว่ามีอะไรเปลี่ยน ใช้ Webhooks แทนการเรียก API วนถาม จะประหยัดโควตากว่า
- อ่าน
X-RateLimit-Remainingแล้วชะลอเมื่อใกล้หมด - ส่งข้อความผ่าน API ยังต้องทำตามกฎของแพลตฟอร์ม เช่น ช่วงเวลาตอบ 24 ชั่วโมงของ Messenger ดู ภาพรวมช่องทาง
ปัญหาที่พบบ่อย #
- 401 — key ผิด ถูกลบ หรือหมดอายุ ดู API keys
- 403
API_SCOPE_DENIED— key ไม่มี scope ที่ endpoint ต้องการ ดูคอลัมน์ Scope ในตาราง แล้วแก้สิทธิ์ของ key - 409
IDEMPOTENCY_KEY_REUSED— ใช้Idempotency-Keyเดิมกับคำขออื่น ให้สร้างค่าใหม่ทุกคำขอ - 429
API_RATE_LIMITED— เรียกเร็วหรือบ่อยเกิน รอตามRetry-Afterแล้วลองใหม่ - 400
INVALID_CURSOR— ใช้ค่าnext_cursorจากผลลัพธ์ก่อนหน้าเท่านั้น อย่าสร้างเอง - ส่งข้อความไม่ได้ — หมดช่วงเวลาตอบของแพลตฟอร์ม ช่องทางหลุด หรือ ticket อยู่ในสแปม ดู ตอบแชท
หน้านี้มีประโยชน์ไหม?