นัก​พัฒนา

Wisebird API: ต่อ​แชท​ลูกค้า​เข้า⁠กับระบบ​ของ​คุณ

REST API, Webhook และ MCP สำหรับ​ต่อ​กับ​ระบบ​ของ​คุณ

อ่าน​คำ⁠อธิบาย​เต็ม

Wisebird API ของ​นัก​พัฒนา​คือ REST API และ Webhook สำหรับ​ดึง​แชท ค้นหา ส่ง​ข้อความ จัดการ​แท็ก​และ​สมาชิก​ของ​ธุรกิจ ด้วย API key ต่อ​ธุรกิจ​และ Bearer auth รองรับ Idempotency-Key, Webhook ที่​มี​ลาย⁠เซ็น​พร้อม test event, sandbox แบบ Try it, MCP และ partner API สำหรับ​ดูแล​หลาย​ธุรกิจ

เริ่ม​ใช้ API ต้อง​มี​อะไร

  1. สร้าง API key ต่อ​ธุรกิจที่​ตั้ง⁠ค่า​ธุรกิจ​ใน​แอป คัด⁠ลอก​เก็บ​ทันที key แสดง​เต็ม​ครั้ง​เดียว
  2. ส่ง key แบบ Bearerใน header Authorization ทุก​คำขอ ห้าม​ใส่ query string ใช้ HTTPS
  3. ทดสอบ​ใน sandbox ก่อนโหมด Try it ใน​แอป​ยิง​คำขอ​ไป​ธุรกิจ​ทดสอบ แล้ว​ค่อย​ใช้ key ธุรกิจ​จริง

ตัวอย่าง · ดึง​รายการ​แชท

curl https://wisebird.cloud/external/v1/conversations?status=open&limit=20 \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx"

มี endpoint อะไร​บ้าง

ทุก endpoint อยู่​ใต้ host เดียว​และ​คืน JSON เอกสาร​เต็ม​พร้อม schema อยู่​ใน​แอป

กลุ่มMethod และ pathใช้​ทำ​อะไร
ConversationsGET /external/v1/conversationsรายการ​แชท กรอง​ตาม​สถานะ ช่อง⁠ทาง แท็ก หรือผู้ดูแล
GET /external/v1/conversations/{id}ราย⁠ละเอียด​แชท​หนึ่ง​รายการ​พร้อม​ข้อความ​และ​การ์ด​ลูกค้า
GET /external/v1/conversations/searchค้นหา​แชท​จาก​ข้อความ ชื่อ​ลูกค้า หรือ​เบอร์​โทร
POST /external/v1/conversations/{id}/messagesส่ง​ข้อความ​ถึง​ลูกค้า รองรับ text, image, video, audio, file
TagsGET, POST /external/v1/tagsอ่าน​และ​สร้าง​แท็ก ติด​หรือ​ถอด​แท็ก​จาก​แชท
MembersGET /external/v1/membersราย⁠ชื่อ​สมาชิก​และ​บทบาท ใช้​มอบ⁠หมาย​แชท
WebhooksGET, POST /external/v1/webhooksลง⁠ทะเบียน endpoint เลือก event และ​ส่ง test event

ตัวอย่าง · ส่ง​ข้อ​ความ⁠พร้อม Idempotency-Key

curl -X POST https://wisebird.cloud/external/v1/conversations/cnv_123/messages \
  -H "Authorization: Bearer wb_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7f3c2a1e-order-4512-confirm" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"รับออเดอร์ #4512 แล้วค่ะ จัดส่งภายใน 2 วันทำการ"}'

# ส่งไฟล์แนบ: เปลี่ยน type เป็น image | video | audio | file และส่ง url ของไฟล์
# -d '{"type":"image","url":"https://example.com/receipt.png","caption":"ใบเสร็จค่ะ"}'
  • Idempotency-Keyค่า​เฉพาะ​ต่อ​ข้อความ ส่ง​ซ้ำ​ด้วย key เดิม​จะ​ได้​ผลลัพธ์​เดิม​และ​ไม่​ส่ง​ซ้ำ​ถึง​ลูกค้า
  • ข้อ⁠จำกัด​ของ​ช่อง⁠ทางประเภท​ไฟล์​และ​ขนาด​ขึ้น⁠กับ​ช่อง⁠ทาง
  • Messengerมี​ข้อ⁠จำกัด 24 ชั่วโมง​สำหรับ​ข้อความ​ที่​ธุรกิจ​เริ่ม​เอง

Webhook แจ้ง​อะไร และ​ตรวจ​ลาย⁠เซ็น​อย่างไร

ลง⁠ทะเบียน endpoint เลือก event แล้ว​กด​ส่ง test event ทดสอบ​ได้​ทันที ไม่⁠ต้อง​รอ​แชท​จริง

Eventv1v2เกิด​เมื่อ
message.receivedมีมีลูก​ค้า⁠ส่ง​ข้อความ​เข้า⁠มา​ใน​ช่อง⁠ทาง​ใด​ก็ตาม
message.sentมีมีAI หรือ​ทีม​ส่ง​ข้อความ​ออก ระบุ​ผู้⁠ส่ง​ใน payload
conversation.handoffมีมีAI ส่ง⁠ต่อ​แชท​ให้​ทีม พร้อม​เหตุผล​และ​สรุป
conversation.assignedไม่​มีมีแชท​ถูก​มอบ⁠หมาย​ให้​สมาชิก
conversation.taggedไม่​มีมีแท็ก​ถูก​เพิ่ม​หรือ​ถอด​จาก​แชท
lead.createdไม่​มีมีฟอร์ม​รับ​ลีด​หรือ AI สร้าง​ลีด​ใหม่​เข้า​ไปป์⁠ไลน์
order.createdไม่​มีมีมี​การ​บันทึก​การ​ขาย​หรือ​ออ⁠เด⁠อร์​จาก​แชท

v2 เพิ่ม event และ​ฟิลด์​ใน payload ส่วน v1 ยัง​ใช้ได้ endpoint ใหม่​แนะนำ v2

ตัวอย่าง · payload และ header ลาย⁠เซ็น​ที่ endpoint ของ​คุณ​จะ​ได้⁠รับ

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Wisebird-Event: conversation.handoff
X-Wisebird-Signature: t=1760600000,v1=5f1c…e2a9
X-Wisebird-Delivery: evt_01HZX…

{"id":"evt_01HZX…","version":"v2","type":"conversation.handoff",
 "business_id":"biz_42","created_at":"2026-10-16T09:30:00+07:00",
 "data":{"conversation_id":"cnv_123","channel":"line","reason":"customer_requested_human",
         "summary":"ลูกค้าถามเรื่องสิวอักเสบก่อนทำทรีตเมนต์ ขอให้แพทย์ประเมิน"}}

# ตรวจลายเซ็น: HMAC-SHA256(secret, t + "." + raw_body) แล้วเทียบกับ v1 แบบ constant-time
# ปฏิเสธถ้า t ห่างจากเวลาปัจจุบันเกินช่วงที่คุณกำหนด เพื่อกัน replay

MCP, sandbox และ partner API

  • Sandbox แบบ Try itหน้า​นัก​พัฒนา​ใน​แอป​ยิง​คำขอ​ไป​ธุรกิจ​ทดสอบ​และ​แสดง⁠ผล​ทันที ไม่​กระทบ​ลูกค้า​จริง
  • MCPให้​เครื่อง⁠มือ AI ภายนอก​เรียก Wisebird เป็น tool ภาย⁠ใต้​สิทธิ์​ของ API key เดียวกัน
  • partner APIkey เดียว​จัดการ​หลาย​ธุรกิจ ใช้​เครดิต​จาก​กระเป๋า​รวม สำหรับพาร์ตเนอร์
  • สิทธิ์​และ logทุก​คำขอ​บันทึก​ใน activity log ยกเลิก key ได้​ทันที​ใน​หน้า​ตั้ง⁠ค่า

ตัวอย่าง · partner API ระบุ​ธุรกิจ​ที่​ต้องการ​จัดการ

curl https://wisebird.cloud/external/v1/conversations?status=open \
  -H "Authorization: Bearer wb_partner_xxxxxxxxxxxxxxxx" \
  -H "X-Wisebird-Business: biz_42"

หน้าที่​เกี่ยวข้อง

โปรแกรม​พาร์ตเนอร์

บริหาร​หลาย​ธุรกิจ กระเป๋า​เครดิต​รวม และ​แพ็ก⁠เกจ​กลาง

ดู​ราย⁠ละเอียด

คำถามที่พบบ่อย

สร้าง API key ของ Wisebird ได้ที่ไหน

สร้างในหน้าตั้งค่าของธุรกิจในแอป key แสดงเต็มครั้งเดียวตอนสร้าง ให้คัดลอกเก็บทันที ทำหายให้ยกเลิกแล้วสร้างใหม่

ส่ง API key ใน query string ได้ไหม

ไม่ได้ ส่ง key ใน header Authorization แบบ Bearer ผ่าน HTTPS เท่านั้น key ใน query string จะถูกปฏิเสธ เพราะ URL มักถูกบันทึกใน log

ถ้าส่งข้อความซ้ำโดยไม่ตั้งใจจะเกิดอะไรขึ้น

ใส่ header Idempotency-Key เป็นค่าเฉพาะต่อข้อความ ส่งซ้ำด้วย key เดิมจะได้ผลลัพธ์เดิมและไม่ส่งซ้ำถึงลูกค้า เหมาะกับการ retry

ตรวจสอบว่า Webhook มาจาก Wisebird จริงอย่างไร

ทุก event มีลายเซ็นใน header คำนวณจาก secret ของ endpoint ให้คำนวณจาก body ดิบแล้วเทียบก่อนประมวลผล กดส่ง test event เพื่อทดสอบได้

มี sandbox ให้ทดสอบโดยไม่กระทบลูกค้าจริงไหม

มี โหมด Try it ในหน้านักพัฒนาของแอปยิงคำขอไปธุรกิจทดสอบ ไม่ส่งถึงลูกค้าจริง และส่ง Webhook test event ด้วยลายเซ็นจริงได้

MCP กับ Wisebird ใช้ทำอะไร

ให้เครื่องมือ AI ภายนอกเรียกความสามารถของ Wisebird เป็น tool เช่น ค้นแชท ดึงการ์ดลูกค้า ส่งข้อความ ภายใต้สิทธิ์ของ API key เดียวกัน

สร้าง API key แรก​ได้​ใน​แพ็ก⁠เกจ​ฟรี

สมัคร เชื่อม​ช่อง⁠ทาง แล้ว​ลอง​ยิง​คำขอ​แรก​ใน sandbox