เชื่อมแอปของคุณด้วย API และ Webhook

ใช้ Third-party API เพื่อนำบอท Konkui ไปไว้ในเว็บไซต์ แอป หรือระบบหลังบ้านของคุณเอง เซิร์ฟเวอร์ของคุณจะเริ่มบทสนทนาให้ลูกค้า ส่งข้อความของลูกค้า และรับคำตอบของบอท ทั้งแบบดึงข้อมูลเอง (Polling) หรือให้ Konkui ส่งมาให้ (Webhook)

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

ก่อนเริ่ม

• ต้องเป็นผู้ดูแลระบบ เฉพาะผู้ดูแลระบบของเวิร์กสเปซที่เปิดนักพัฒนาได้
• บอทควรตอบได้ดีในทดสอบบอทแล้ว ดูทดสอบและปรับปรุงบอท
• เรียก API จากเซิร์ฟเวอร์เท่านั้น API key เป็นข้อมูลลับ ห้ามใส่ไว้ในโค้ดฝั่งเบราว์เซอร์หรือแอปมือถือ

1. ลองในพื้นที่ทดลองก่อน (ไม่บังคับ)

ก่อนเขียนโค้ด เปิดนักพัฒนา › ทดลองเรียก API เพื่อลองคุยกับบอทผ่าน API จริง

1. คลิก รับข้อมูลรับรองสำหรับทดลอง (อายุไม่เกิน 1 วัน)
2. ใช้ รหัสลูกค้า ที่ใส่ไว้ให้ หรือกรอกเอง
3. คลิก เริ่มบทสนทนา เลือก สถานการณ์ตัวอย่าง ได้หากต้องการ แล้วพิมพ์ข้อความและส่ง

ข้อมูลรับรองสำหรับทดลองจะแสดงในหน้า API Keys เพิกถอนได้ที่นั่นเมื่อทดลองเสร็จ

2. สร้าง API key

1. เปิดนักพัฒนา › API Keys แล้วคลิก สร้าง API Key
2. ตั้ง ชื่อคีย์ ที่จำได้ง่าย เช่น "Production Key" แล้วคลิก สร้างคีย์
3. คัดลอกคีย์จากกล่อง สร้าง API Key สำเร็จ! ไปเก็บในที่เก็บข้อมูลลับของเซิร์ฟเวอร์ คีย์จะแสดงเพียงครั้งเดียว

คีย์ที่สร้างจากหน้านี้อ่านและเขียนบทสนทนาได้ หากคีย์รั่วไหล ให้เพิกถอนจากเมนู ⋮ ด้วย เพิกถอนคีย์ แล้วสร้างคีย์ใหม่

3. เรียก API

ทุกคำขอส่งไปที่ https://konkui.com/api/thirdparty/… โดยใส่คีย์เป็น Bearer token

curl -X POST "https://konkui.com/api/thirdparty/validate" \
  -H "Authorization: Bearer $KONKUI_API_KEY"

validate ตอบกลับ { "valid": true, "orgId": "…" } จึงเหมาะใช้ตรวจตอนแอปเริ่มทำงาน

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

curl -X POST "https://konkui.com/api/thirdparty/start-conversation" \
  -H "Authorization: Bearer $KONKUI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "customerId": "customer_123", "metadata": { "source": "mobile-app" } }'

ส่งข้อความของลูกค้า การตอบกลับจะมี reply ของบอท และ products ที่แนะนำ (ถ้ามี)

curl -X POST "https://konkui.com/api/thirdparty/send-message" \
  -H "Authorization: Bearer $KONKUI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "conversationId": "YOUR_CONVERSATION_ID", "message": "I need help with my order", "messageType": "TEXT" }'

การตอบกลับที่สำเร็จอยู่ในรูป { "success": true, "data": …, "timestamp": … } ส่วนข้อผิดพลาดจะได้ success: false พร้อม error.message

4. รับคำตอบ: Polling หรือ Webhook

เลือกแบบที่เหมาะกับแอปของคุณ แท็บเอกสารมีเอกสารอ้างอิงครบทั้งสองแบบ

Polling

เรียก receive-reply หลังส่งข้อความหรือเรียกเป็นระยะ เพื่อดึงข้อความใหม่ตามลำดับเวลา ส่ง afterTimestamp เพื่อขอเฉพาะข้อความที่ใหม่กว่าข้อความล่าสุดที่เห็น และใช้ limit กำหนดจำนวนต่อครั้ง

curl -X POST "https://konkui.com/api/thirdparty/receive-reply" \
  -H "Authorization: Bearer $KONKUI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "conversationId": "YOUR_CONVERSATION_ID", "limit": 20, "afterTimestamp": "2026-10-06T10:00:00.000Z" }'

Polling ง่ายที่สุดเมื่อแอปของคุณรอคำตอบของแต่ละข้อความอยู่แล้ว

Webhook

ด้วย Webhook ระบบ Konkui จะส่งอีเวนต์ไปยังเซิร์ฟเวอร์ของคุณทันทีที่เกิดขึ้น

1. เปิดนักพัฒนา › Webhooks แล้วคลิก เพิ่ม Webhook
2. กรอก Webhook URL (ควรใช้ HTTPS) และเลือก อีเวนต์ที่ต้องการติดตาม ได้แก่ เริ่มบทสนทนา ได้รับข้อความ ส่งข้อความแล้ว
3. คลิก เพิ่ม Webhook แล้วคัดลอกซีเคร็ตจากกล่อง กรุณาคัดลอกซีเคร็ต webhook นี้ตอนนี้ ไปไว้ที่เซิร์ฟเวอร์ และคลิก บันทึกไว้แล้ว ซีเคร็ตจะแสดงเพียงครั้งเดียว

แต่ละครั้งที่ส่งเป็น POST แบบ JSON ที่มี event, timestamp, organizationId และ data พร้อมส่วนหัวต่อไปนี้

ตอบกลับด้วยสถานะ 2xx ให้เร็ว สถานะอื่นจะถูกส่งซ้ำอัตโนมัติ (รวมไม่เกิน 3 ครั้ง หลังประมาณ 1 นาที และ 5 นาที)

ทดสอบและแก้ปัญหา Webhook

• คลิก ทดสอบ ที่ Webhook เพื่อส่งอีเวนต์ test ที่ลงลายเซ็นแล้วทันที ระบบจะแจ้งสถานะ HTTP ที่เซิร์ฟเวอร์ของคุณตอบกลับ
• คลิก ประวัติการส่ง เพื่อดูการส่งล่าสุดพร้อมสถานะ รหัส HTTP จำนวนครั้งที่ลอง และข้อผิดพลาดล่าสุด เมื่อแก้เซิร์ฟเวอร์แล้ว คลิก ลองใหม่ ที่รายการ FAILED
• ใช้สวิตช์ของ Webhook เพื่อหยุดส่งชั่วคราวระหว่างแก้ไขเซิร์ฟเวอร์

5. รีเฟรชโทเค็นให้ใช้งานต่อเนื่อง

โทเค็น API หมดอายุ 1 วัน หลังออกให้ ก่อนหมดอายุให้แลกโทเค็นปัจจุบันเป็นโทเค็นใหม่

curl -X POST "https://konkui.com/api/thirdparty/refresh" \
  -H "Content-Type: application/json" \
  --data "{\"token\":\"$KONKUI_API_KEY\"}"

การตอบกลับมี token ใหม่ พร้อม expiresIn และ expiresAt บันทึกโทเค็นใหม่แล้วเลิกใช้โทเค็นเดิม เพราะโทเค็นเดิมจะใช้ไม่ได้ทันทีที่รีเฟรชสำเร็จ

• รีเฟรชก่อนหมดอายุเล็กน้อย (เช่น 30 วินาที) และให้มีการรีเฟรชทีละครั้งเท่านั้น
• โทเค็นที่หมดอายุแล้วยังรีเฟรชได้ภายใน 1 ชั่วโมง หลังหมดอายุ หากเกินกว่านั้นให้สร้างคีย์ใหม่
• คู่มือการรีเฟรช Token ในนักพัฒนา › เอกสาร มีโค้ดตัวอย่างสำหรับรีเฟรชอัตโนมัติ

6. ตรวจว่าได้ผล

• นักพัฒนา › ภาพรวม แสดง การเรียก API วันนี้ และ อัตราสำเร็จ
• นักพัฒนา › สถิติการใช้งาน แสดงกราฟจำนวนการเรียกต่อวันและเอนด์พอยต์ยอดนิยม
• บทสนทนาที่เริ่มผ่าน API นับรวมในบทสนทนาและการใช้งาน AI ของแพ็กเกจเหมือนช่องทางอื่น ติดตามได้ที่ตั้งค่า › การใช้งาน

หัวข้อที่เกี่ยวข้อง

• นักพัฒนา
• ดูรายงานและการใช้งาน
• ทดสอบและปรับปรุงบอท
• การชำระเงินและแพ็กเกจ