修改對話狀態
透過 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)"
}
此代碼塊在浮窗中顯示
