อัปเดตสถานะการสนทนา
ใช้ API toggle_status เพื่อเปลี่ยนสถานะของการสนทนาที่ระบุ เซิร์ฟเวอร์จะตรวจสอบว่าสถานะเป้าหมายถูกต้องตาม เมทริกซ์การเปลี่ยนสถานะ STATUS_TRANSITIONS หรือไม่
วิธีการส่งคำขอ
POST
URL สำหรับส่งคำขอ
https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status
การตรวจสอบสิทธิ์
ดูรายละเอียดได้ที่คำแนะนำเกี่ยวกับการตรวจสอบสิทธิ์ใน ภาพรวม API
คำขอ
ตัวอย่างคำขอ
curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
"status": "resolved",
"snoozed_until": 1715000000
}'
curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
"status": "resolved",
"snoozed_until": 1715000000
}'
โค้ดนี้โชว์เป็นหน้าต่างลอย
ส่วนหัวคำขอ
| Field | Type | Description |
|---|---|---|
| Authorization | string | ตรวจสอบสิทธิ์โดยใช้ Authorization: Basic base64(API Key:API Secret) ไปที่หน้าคีย์ API เพื่อรับ API key และ API secret จากนั้นคั่นค่าทั้งสองด้วยเครื่องหมายโคลอนและเข้ารหัสผลลัพธ์เป็น Base64 |
| Content-Type | application/json | ประเภทข้อมูล ใช้ application/json สำหรับข้อมูลข้อความทั่วไป |
พารามิเตอร์พาธ
| Field | Type | Required | Description |
|---|---|---|---|
| conversation_id | string | Yes | ID ของการสนทนา |
พารามิเตอร์ในเนื้อหาคำขอ
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | สถานะเป้าหมาย ดูค่าที่ระบุไว้ด้านล่าง |
| snoozed_until | integer | No | มีผลเฉพาะเมื่อ status=snoozed เท่านั้น เป็น UNIX timestamp ในหน่วยวินาที หากไม่ระบุ การสนทนาจะถูกเลื่อนการแจ้งเตือนออกไปอย่างไม่มีกำหนด |
| sender_type | string | No | ใช้สำหรับการระบุภายในฝั่งเซิร์ฟเวอร์เท่านั้น เมื่อผู้เรียกคือ AgentBot สถานะปัจจุบันคือ pending และสถานะเป้าหมายคือ open ระบบจะทริกเกอร์กระบวนการ bot_handoff! และส่งอีเวนต์ CONVERSATION_BOT_HANDOFF |
ค่าที่ระบุไว้ของ status
| Value | Meaning |
|---|---|
| open | เปิด |
| resolved | แก้ไขแล้ว |
| pending | รอการจัดการโดยบอตหรือเจ้าหน้าที่ |
| snoozed | เลื่อนการแจ้งเตือน |
| closed | ปิด (เก็บถาวร) |
เมทริกซ์การเปลี่ยนสถานะ (STATUS_TRANSITIONS)
| Current Status | Allowed Transitions |
|---|---|
| open | open, resolved, pending, snoozed |
| resolved | resolved, open, pending, snoozed, closed |
| pending | pending, open, resolved, snoozed |
| snoozed | snoozed, open, resolved, pending |
| closed | closed, open |
ข้อจำกัดสำคัญ
resolvedเป็นสถานะเดียวที่ต้องเกิดขึ้นก่อนเปลี่ยนเป็นclosed:open,pendingและsnoozedไม่สามารถเปลี่ยนเป็นclosedได้โดยตรง ต้องเปลี่ยนเป็นresolvedก่อนจึงจะเก็บถาวรได้closedสามารถเปลี่ยนกลับเป็นopenได้เท่านั้น: การสนทนาที่เก็บถาวรแล้วไม่สามารถเปลี่ยนโดยตรงไปยังสถานะใช้งานอื่น ๆ เช่นresolved,pendingหรือsnoozed- การกำหนดสถานะเดิมซ้ำเป็น Idempotent: เมื่อสถานะเป้าหมายเหมือนกับสถานะปัจจุบัน ระบบจะข้ามการตรวจสอบและดำเนินการตามคำขอให้สำเร็จโดยตรง โดยจะไม่ทริกเกอร์ callback
- ระบบตรวจสอบนี้ทำงานที่ชั้นโมเดล ActiveRecord ผ่าน
validate :status_transition_allowed, if: :will_save_change_to_status?และมีผลกับเส้นทางsave!,update!และstatus=ตามด้วยsaveทั้งหมด
การตอบกลับ
การตอบกลับเมื่อสำเร็จ
HTTP 200:
{
"meta": {},
"payload": {
"success": true,
"conversation_id": 45,
"current_status": "resolved",
"snoozed_until": null
}
}
{
"meta": {},
"payload": {
"success": true,
"conversation_id": 45,
"current_status": "resolved",
"snoozed_until": null
}
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
พารามิเตอร์การตอบกลับ
| Field | Type | Description |
|---|---|---|
| success | boolean | ค่าที่ส่งกลับจาก save; เป็น true เมื่อเปลี่ยนสถานะสำเร็จ |
| conversation_id | integer | display_id ของการสนทนา ซึ่งเป็น ID ที่มองเห็นได้ภายในบัญชี |
| current_status | string | สถานะของการสนทนาหลังการเปลี่ยนแปลง |
| snoozed_until | integer / null | timestamp วันหมดอายุของการเลื่อนการแจ้งเตือนที่มีผลอยู่ในปัจจุบัน โดยเป็น null เสมอสำหรับสถานะที่ไม่ใช่ snoozed |
การตอบกลับเมื่อเกิดข้อผิดพลาด
| HTTP Status Code | Trigger Condition |
|---|---|
| 401 | ไม่ได้ตรวจสอบสิทธิ์หรือการตรวจสอบสิทธิ์ล้มเหลว |
| 403 | ผู้ใช้ปัจจุบันไม่มีสิทธิ์เข้าถึง Inbox ที่การสนทนานั้นสังกัดอยู่ |
| 404 | ไม่พบการสนทนาที่มี display_id ตรงกันในบัญชีปัจจุบัน |
| 422 | status ไม่ใช่ค่าที่ระบุไว้ที่ถูกต้อง การแยกวิเคราะห์ snoozed_until ล้มเหลว หรือสถานะเป้าหมายไม่เป็นไปตามเมทริกซ์ STATUS_TRANSITIONS |
โครงสร้างการตอบกลับ 422
การละเมิดเมทริกซ์การเปลี่ยนสถานะ (จากการตรวจสอบระดับโมเดลและแสดงผลเป็น full_messages โดย RequestExceptionHandler):
{
"message": "Status can't transition from open to closed",
"attributes": ["status"]
}
{
"message": "Status can't transition from open to closed",
"attributes": ["status"]
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
ค่าที่ระบุไว้ของสถานะไม่รู้จัก (จาก CustomExceptions::Conversation::InvalidStatus):
{
"message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)"
}
{
"message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)"
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
snoozed_until ไม่ถูกต้อง (จาก CustomExceptions::Conversation::InvalidSnoozedUntil):
{
"message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)"
}
{
"message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)"
}
โค้ดนี้โชว์เป็นหน้าต่างลอย
