更新對話狀態
透過 toggle_status 介面變更指定會話的狀態，伺服器端會依照 STATUS_TRANSITIONS 狀態遷移矩陣 驗證目標狀態是否合法。
請求方式
POST
呼叫位址
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
}'
此代碼塊在浮窗中顯示
請求頭
| 欄位 | 類型 | 描述 |
|---|---|---|
| Authorization | string | 使用 Authorization: Basic base64(API Key:API Secret) 進行身分驗證。請前往 API 金鑰頁面取得 API Key 與 API Secret，並將兩者以冒號連接後進行 Base64 編碼。 |
| Content-Type | application/json | 資料類型，一般文字訊息使用 application/json。 |
路徑參數
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| conversation_id | string | 是 | 對話 ID。 |
請求本文參數
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| status | string | 是 | 目標狀態，列舉值請見下方 |
| snoozed_until | integer | 否 | 僅在 status=snoozed 時生效，UNIX 時間戳記（秒）。未傳入表示無限期暫存 |
| sender_type | string | 否 | 僅供伺服器端內部識別用途。當呼叫方為 AgentBot，且目前狀態為 pending、目標狀態為 open 時，會觸發 bot_handoff! 流程並派發 CONVERSATION_BOT_HANDOFF 事件 |
status 列舉值
| 值 | 含義 |
|---|---|
| open | 進行中 |
| resolved | 已解決 |
| pending | 待 Bot／客服處理 |
| snoozed | 暫存 |
| closed | 已關閉（封存） |
狀態遷移矩陣（STATUS_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等其他處理中狀態。- 同狀態寫入具有冪等性：目標狀態等於目前狀態時，會跳過驗證並直接回傳成功，不會觸發回呼。
- 驗證是在 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
}
}
此代碼塊在浮窗中顯示
回應參數
| 欄位 | 類型 | 說明 |
|---|---|---|
| success | boolean | save 的回傳值；狀態變更成功時為 true |
| conversation_id | integer | 會話的 display_id（帳戶內可見 ID） |
| current_status | string | 變更後的會話狀態 |
| snoozed_until | integer / null | 目前生效的 snooze 到期時間戳記；非 snoozed 狀態固定為 null |
錯誤回應
| HTTP 狀態碼 | 觸發條件 |
|---|---|
| 401 | 未驗證／驗證失敗 |
| 403 | 目前使用者對該會話所屬 Inbox 沒有存取權限 |
| 404 | 在目前帳戶下找不到對應 display_id 的會話 |
| 422 | status 不是合法列舉值、snoozed_until 解析失敗，或目標狀態違反 STATUS_TRANSITIONS 矩陣 |
422 回應結構
違反狀態遷移矩陣（來自模型層驗證，由 RequestExceptionHandler 渲染為 full_messages）：
{
"message": "Status can't transition from open to closed",
"attributes": ["status"]
}
{
"message": "Status can't transition from open to closed",
"attributes": ["status"]
}
此代碼塊在浮窗中顯示
未知的 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)"
}
此代碼塊在浮窗中顯示
