Khuivo
นักพัฒนา

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. 1

    สร้าง key ที่ API keys ให้สิทธิ์อ่าน Ticket อย่างน้อย

  2. 2

    เปิดแท็บ เอกสาร API แล้วคัดลอก Base URL

  3. 3

    ตั้งค่าตัวแปรใน terminal แล้วเรียก /me เพื่อตรวจว่า key ใช้ได้

  4. 4

    ลองเรียก /tickets ตามตัวอย่างด้านล่าง

ตั้งค่าและทดสอบ key
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 พร้อม header Retry-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

MethodPathScopeใช้ทำอะไร
GET/me—ข้อมูล key และ workspace
GET/ticketstickets:readรายการ ticket กรองด้วย status, q, contact_id, assignee_id, channel_account_id
GET/tickets/{id}tickets:readticket หนึ่งใบ
PATCH/tickets/{id}tickets:writeแก้ subject, priority, fields
POST/tickets/{id}/assigntickets:writeมอบหมายด้วย user_id หรือ team_id
POST/tickets/{id}/closetickets:writeปิด ticket ใส่ reason ได้
POST/tickets/{id}/reopentickets:writeเปิด ticket อีกครั้ง
GET/tickets/{id}/notesmessages:readโน้ตภายในของ ticket
POST/tickets/{id}/notesmessages:writeเขียนโน้ตภายใน (text)
GET/conversationsconversations:readรายการบทสนทนา
GET/conversations/{id}conversations:readบทสนทนาหนึ่งรายการ
POST/conversations/{id}/readconversations:writeทำเครื่องหมายว่าอ่านแล้ว
POST/conversations/{id}/labelsconversations:writeติด label (label_ids)
DELETE/conversations/{id}/labels/{labelId}conversations:writeถอด label
GET/conversations/{id}/messagesmessages:readข้อความในบทสนทนา
POST/conversations/{id}/messagesmessages:writeส่งข้อความถึงลูกค้า
GET/messages/searchmessages:readค้นหาข้อความ (q)
GET/contactscontacts:readรายชื่อลูกค้า ค้นหาด้วย q
POST/contactscontacts:writeสร้างลูกค้า
GET/contacts/{id}contacts:readลูกค้าหนึ่งราย
PATCH/contacts/{id}contacts:writeแก้ข้อมูลลูกค้า
POST/contacts/{id}/mergecontacts:writeรวมลูกค้า source_contact_id เข้ากับรายนี้
GET/accountsaccounts:readช่องทางที่เชื่อมไว้
GET/usersusers:readสมาชิกใน workspace
GET/teamsteams:readทีม
GET/labelslabels:readlabel
GET/analytics/summaryanalytics:readสรุปรายงาน
GET/analytics/eventsanalytics:readevent ตามช่วงเวลา (from, to, types)

Open API ไม่มี endpoint สำหรับออเดอร์และสินค้า

ตัวอย่าง #

ดึง ticket ที่เปิดอยู่ 20 ใบแรก แล้วขอหน้าถัดไปด้วย next_cursor:

ดึง ticket ที่เปิดอยู่
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 เป็นข้อความแจ้งเตือน:

ส่ง Flex Message
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} ในข้อความที่แก้ได้:

แก้ Flex Message สำหรับการส่งครั้งนี้
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:

ปิด 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 อยู่ในสแปม ดู ตอบแชท

หน้านี้มีประโยชน์ไหม?