อัปเดตสถานะการสนทนา

ใช้ API toggle_status เพื่อเปลี่ยนสถานะของการสนทนาที่ระบุ โดยเซิร์ฟเวอร์จะตรวจสอบว่าสถานะเป้าหมายถูกต้องตามเมทริกซ์การเปลี่ยนสถานะ STATUS_TRANSITIONS หรือไม่

วิธีการร้องขอ

POST

Endpoint

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 ของการสนทนา

พารามิเตอร์ Request Body

Field	Type	Required	Description
status	string	Yes	สถานะเป้าหมาย ดูค่า enum ด้านล่าง
snoozed_until	integer	No	มีผลเฉพาะเมื่อ `status=snoozed` เท่านั้น เป็น UNIX timestamp (วินาที) หากละไว้ การสนทนาจะถูกพักไว้แบบไม่มีกำหนด
sender_type	string	No	ใช้สำหรับการระบุฝั่งเซิร์ฟเวอร์ภายในเท่านั้น เมื่อผู้เรียกคือ `AgentBot` สถานะปัจจุบันคือ `pending` และสถานะเป้าหมายคือ `open` ระบบจะทริกเกอร์โฟลว์ `bot_handoff!` และส่งอีเวนต์ `CONVERSATION_BOT_HANDOFF`

ค่า enum ของ status

Value	Meaning
open	กำลังดำเนินการ
resolved	แก้ไขแล้ว
pending	รอการจัดการโดยบอท/เอเจนต์
snoozed	พักไว้
closed	ปิดแล้ว (เก็บถาวร)

เมทริกซ์การเปลี่ยนสถานะ (STATUS_TRANSITIONS)

Current Status	Allowed Target Status
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` ไม่ใช่ค่า enum ที่ถูกต้อง, `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"]
}

โค้ดนี้โชว์เป็นหน้าต่างลอย

ไม่รู้จักค่า enum ของ 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)"
}

โค้ดนี้โชว์เป็นหน้าต่างลอย