API สาธารณะ Beta

ค้นหาบทสนทนาที่ต้องดูแล

กรองตาม awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority หรือ tagIds การรอตอบกลับ (awaitingReply) ไม่นับโน้ตภายใน ส่วน unread เป็นข้อมูลเฉพาะของสมาชิกทีมที่ยืนยันตัวตนอยู่ unassigned หมายถึงไม่มีผู้รับผิดชอบรายบุคคล แม้จะมอบหมายให้ทีมแล้วก็ตาม แท็กจะตรงเมื่อมี ID ใดก็ได้ที่ส่งมา ส่ง propertyId (ฟิลด์ประเภท Select จาก list_properties) พร้อม propertyValues เพื่อจับคู่ผู้ติดต่อที่มีตัวเลือกใดตัวเลือกหนึ่งในนั้น สำหรับ REST ให้ใส่ propertyValues ซ้ำหนึ่งครั้งต่อหนึ่งตัวเลือก

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

เรียงลำดับตาม waitingSince, lastMessageAt, createdAt หรือความสำคัญทางธุรกิจ โดยกำหนดทิศทางเป็น asc หรือ desc หากค่าเท่ากันจะใช้ ID ตัดสิน ตัวกรองที่ไม่ได้ระบุจะคงค่า compact=false และ snoozed=any ไว้ tagIds ใน REST รับ ID ที่คั่นด้วยจุลภาค ส่วน MCP รับแบบอาร์เรย์ได้ด้วย waitingSince เริ่มนับที่ข้อความขาเข้าข้อความแรกหลังการตอบกลับล่าสุด ข้อความติดตามผลและโน้ตภายในจะไม่รีเซ็ตค่านี้ ให้ตั้งเวลาสแกนคิวรอนี้เป็นประจำแม้ไม่มีเว็บฮุกเข้ามา เพื่อให้เธรดเก่ากลับขึ้นมาให้เห็น

ตามทันการเปลี่ยนแปลงโดยไม่ต้องอ่านกล่องข้อความซ้ำ

ใช้ GET /api/v1/sync พร้อม conversations:read ฟีดแบบถาวรนี้มีการเปลี่ยนแปลงของบทสนทนา แท็ก ข้อความ ฟิลด์ของผู้ติดต่อ ความจำ และบันทึกการลบ payload แต่ละประเภทยังต้องใช้ขอบเขตสิทธิ์การอ่านของตนเองด้วย เนื้อหาข้อความต้องใช้ messages:read และความจำต้องใช้ contact-memory:read ข้อมูลรับรองที่ถูกจำกัดจะได้รับเฉพาะช่องทางที่ได้รับอนุญาต

1. เริ่มโดยไม่ใส่เคอร์เซอร์ ทำตาม nextCursor ไปจนกว่า hasMore จะเป็น false แล้วบันทึกเคอร์เซอร์นั้นไว้
2. อ่านรายการบทสนทนา/ผู้ติดต่อปัจจุบันและประวัติที่คุณต้องใช้สำหรับสถานะเริ่มต้น
3. เล่นซ้ำจากเคอร์เซอร์ที่บันทึกไว้เพื่อเก็บการเปลี่ยนแปลงที่เกิดขึ้นระหว่างการอ่านนั้น ประมวลผลแต่ละหน้า แล้วบันทึก nextCursor

ตัดรายการซ้ำด้วย id ของอีเวนต์ เนื่องจากการเล่นซ้ำรับประกันแบบอย่างน้อยหนึ่งครั้ง (at least once) การดำเนินการปลายทางจึงต้องมีการป้องกันการซ้ำของตนเอง คำขอที่ไม่มีเคอร์เซอร์จะครอบคลุมเฉพาะชั่วโมงล่าสุด ไม่ใช่สแนปช็อตทั้งหมด อีเวนต์จะถูกเก็บไว้ 30 วัน HTTP 410 resync_required หมายถึงต้องโหลดสถานะเริ่มต้นใหม่ และควรโหลดสถานะเริ่มต้นใหม่หลังขยายขอบเขตสิทธิ์หรือสิทธิ์เข้าถึงช่องทางด้วย ใช้ limit ได้สูงสุด 100 และ maxBodyChars ได้สูงสุด 10,000 (ค่าเริ่มต้น 500) ตั้ง compact=true เพื่อรับฟิลด์ textPreview/textTruncated ของข้อความที่จำกัดไว้ 200 ตัวอักษรแทน body/bodyTruncated เว็บฮุกปลุกเอเจนต์ได้ ส่วนฟีดยังใช้ได้แม้ไม่ได้สมัครรับเว็บฮุก หรือเมื่อการส่งเว็บฮุกค้างอยู่

บันทึกการตรวจสอบครั้งเดียวและแชร์ผลลัพธ์

ก่อนตรวจสอบเรื่องเดิมซ้ำ ให้อ่าน list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks) บันทึกผลด้วย record_conversation_check (PUT ไปยังพาธเดียวกัน) โดยระบุ key, result, checkedBy และ reference ซึ่งไม่บังคับสำหรับ ID หรือ URL ของการ์ด ตัวอย่างเช่น key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X แล้ว Sonny จะบันทึก actorId ที่ยืนยันตัวตนและเวลา checkedAt การใช้ key ซ้ำจะแทนที่เฉพาะการตรวจสอบนั้น ข้อมูลนี้เป็นสถานะปัจจุบัน ไม่ใช่บันทึกประวัติ การอ่านต้องใช้ conversations:read และการเขียนต้องใช้ conversations:write โดยทั้งสองอย่างจำกัดตามช่องทางของบทสนทนา การเรียกเหล่านี้จะไม่ส่งคำตอบหรือทำเครื่องหมายว่าตอบผู้ขายแล้ว

มอบหมายและอัปเดตงานเป็นชุด

ดูสมาชิกทีมและทีมที่ใช้งานอยู่และมอบหมายได้ด้วย GET /api/v1/members and /teams (members:read) การตอบกลับมีสถานะพร้อมให้บริการและสิทธิ์เข้าถึงช่องทางที่มีผลจริง โดยไม่มีอีเมล ใช้ conversations:write เพื่อเปลี่ยน status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds หรือ removeTagIds

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

การกระจายงานแบบวนรอบ (round-robin) จะเลือกสมาชิกทีมที่พร้อมให้บริการและเข้าถึงช่องทางของบทสนทนาได้ หากไม่มีสมาชิกที่เข้าเกณฑ์ การอัปเดตรายการเดียวจะส่งกลับ 409 และรายการในชุดจะล้มเหลว แต่ละชุดรับ ID ที่ไม่ซ้ำกันได้สูงสุด 100 รายการ และใช้การแก้ไขหนึ่งชุดแบบ atomic ต่อบทสนทนา ตรวจสอบผลลัพธ์ { id, ok, error? } ทุกรายการ เพราะบางรายการอาจล้มเหลว ชุดคำขอใช้ขีดจำกัดอัตราตามจำนวนคำขอปัจจุบัน โดยไม่คิดน้ำหนักตามจำนวนรายการ

แชร์บริบทของลูกค้ากับ Sonny AI

แสดงรายการ บันทึก และนำความจำของผู้ติดต่อออกด้วย contact-memory:read/write ระบุทั้ง contactId และ sourceId ที่เข้าถึงได้ โดยผู้ติดต่อต้องมีบทสนทนาในช่องทางนั้น ข้อเท็จจริงที่บันทึกจะใช้การตรวจสอบ การจัดการข้อมูลซ้ำ และขีดจำกัดเดียวกับในแอป และบันทึกเป็นความจำที่เพิ่มด้วยตนเอง

อ่านคำจำกัดความของฟิลด์ที่ /api/v1/properties และอ่านหรือตั้งค่าที่ /api/v1/contacts/{contactId}/properties MCP มี list_properties, get_contact_properties และ set_contact_property ซึ่งต้องใช้ contacts:read/write และสิทธิ์เข้าถึงทุกช่องทาง ระบุ propertyId หรือ propertyName อย่างใดอย่างหนึ่งเท่านั้น พร้อมค่าสตริง หรือ null เพื่อล้างค่า ค่าข้อความ ตัวเลข URL วันที่ และตัวเลือกจะถูกตรวจสอบตามคำจำกัดความของฟิลด์

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

ตัวกรองฟิลด์จะจับคู่กับสตริงที่จัดเก็บไว้แบบตรงตัว หากใช้หลายฟิลด์ ต้องตรงทั้งหมด ค่าที่เขียนผ่าน API จะถูกระบุว่าเป็นข้อมูลจาก API ใน Co-Pilot และระบบตอบกลับอัตโนมัติ กฎเดิมเกี่ยวกับลูกค้าที่ยืนยันแล้วและช่องทางยังคงมีผล ค่าฟิลด์ภายในที่กรอกด้วยตนเองตามปกติยังคงไม่รวมอยู่ในบริบท AI นี้

อ่านรายงานชุดเดียวกับที่ทีมของคุณเห็น

เมื่อมี reporting:read ให้เรียก GET /api/v1/reporting/{kind} ประเภทรายงานได้แก่ overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads และ online-hours โดย overview จะรวมจำนวน เวลาตอบกลับ และ CSAT ไว้ด้วยกัน ตัวกรองได้แก่ period (1–365 วัน ค่าเริ่มต้น 30), วันที่ from/to ที่ใช้คู่กัน (ไม่รวมวันที่ to), granularity (day/month), source, assigneeId และ tagId ค่า source รับ all, all-chat, all-email, website:{id} หรือ email:{id}

รายงานใช้คิวรีเดียวกับแดชบอร์ดและการตรวจสอบสิทธิ์เข้าถึงปัจจุบัน knowledge ใช้วันที่และช่องทางที่ได้รับอนุญาต โดยไม่ขึ้นกับ source ผู้รับผิดชอบ หรือแท็กที่เลือก online-hours วัดการออนไลน์ในเวิร์กสเปซของสมาชิกทีมที่เข้าถึงได้ ส่วนจำนวนบทสนทนายังคงจำกัดตามช่องทาง เอนด์พอยต์ /csat ที่มีอยู่ยังคงใช้ขอบเขตสิทธิ์ csat:read แยกต่างหาก และอาจอธิบายกลุ่มข้อมูลที่ต่างกัน

ส่งไฟล์พร้อมคำตอบหรือโน้ตภายใน

ให้สิทธิ์ attachments:write แล้วอัปโหลดไฟล์ขนาดไม่เกิน 25 MB สำหรับบทสนทนา POST /api/v1/attachments รับฟิลด์ multipart ได้แก่ file และ conversationId การตอบกลับมี id และ expiresAt ส่ง attachmentIds ได้สูงสุด 10 รายการไปกับคำตอบหรือโน้ตภายในหนึ่งชั่วโมง ไฟล์ที่อัปโหลดแต่ละไฟล์ผูกกับผู้ใช้และบทสนทนาของคุณ และใช้ได้เพียงครั้งเดียว ไฟล์ที่ไม่ได้ใช้จะถูกล้างหลังหมดอายุ

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

คำตอบต้องใช้ messages:send ส่วนโน้ตภายในต้องใช้ messages:write และจะไม่ถึงลูกค้า รองรับข้อความที่มีแต่ไฟล์แนบ คำตอบทางอีเมลจะแนบไฟล์ภายในขนาดอีเมลที่กำหนด และให้ลิงก์ดาวน์โหลดสำหรับไฟล์ที่เหลือ อีเมลแชทเมื่อออฟไลน์จะมีลิงก์ไฟล์ ลิงก์ในอีเมลใช้ได้ตราบใดที่ไฟล์แนบยังอยู่ ผู้รับจึงเปิดภายหลังได้ การส่งต่ออีเมลจะเป็นการแชร์สิทธิ์เข้าถึงไฟล์เหล่านั้นด้วย ตรวจสอบ emailDeliveryStatus เพื่อดูการส่งที่ล้มเหลว

การอ่านข้อความที่ได้รับอนุญาตจะมี downloadUrl, downloadExpiresAt, aiStatus, aiDescription และ aiExtractedText รวมถึง videoTranscripts สำหรับวิดีโอที่ลิงก์ไว้ (Loom, Vimeo และอื่นๆ) ลิงก์ดาวน์โหลดมีอายุ 15 นาที อ่านข้อความอีกครั้งเพื่อรับลิงก์ใหม่ ไฟล์ที่อัปโหลดผ่าน API/MCP ใหม่จะจัดเก็บแบบส่วนตัว ไฟล์แนบเก่ายังคงเป็นแบบสาธารณะและถูกระบุเป็น access=legacy_public โดย URL เดิมจะไม่หมดอายุ การอ่านข้อความจะเริ่มอ่านรูปภาพในข้อความเมื่อเวิร์กสเปซมี Sonny AI การอ่านรูปภาพและการถอดความวิดีโอจะเสร็จในไม่ช้าหลังจากข้อความเข้ามา ระหว่างที่ยังทำงานอยู่ การตอบกลับจะขึ้นต้นด้วย readsInProgress ซึ่ง nextStep จะระบุการเรียกที่ต้องทำอย่างชัดเจน ส่ง waitSeconds (สูงสุด 30) เพื่อรอผลในคำขอเดียว ข้อความในวิดเจ็ตที่ลูกค้าเห็นและข้อความแบบเรียลไทม์จะไม่มีข้อมูลที่ดึงออกมาหรือคำถอดความ