Update Conversation Status

Use the toggle_status API to change the status of a specified conversation. The server validates whether the target status is valid according to the STATUS_TRANSITIONS state transition matrix.

Request Method

POST

Endpoint

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status

Authentication

For details, see the authentication method description in API Overview.

Request

Request Example

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
}'

This code block in the floating window

Request Headers

Field	Type	Description
Authorization	string	Use `Authorization: Basic base64(API Key:API Secret)` for authentication. Go to the API key page to obtain the API Key and API Secret, then join them with a colon and encode the result in Base64.
Content-Type	application/json	Content type. Use `application/json` for plain-text messages.

Path Parameters

Field	Type	Required	Description
conversation_id	string	Yes	Conversation ID.

Request Body Parameters

Field	Type	Required	Description
status	string	Yes	Target status. See the enum values below.
snoozed_until	integer	No	Takes effect only when `status=snoozed`. UNIX timestamp (seconds). If omitted, the conversation is snoozed indefinitely.
sender_type	string	No	For internal server-side identification only. When the caller is `AgentBot`, the current status is `pending`, and the target status is `open`, the `bot_handoff!` flow is triggered and the `CONVERSATION_BOT_HANDOFF` event is dispatched.

status Enum Values

Value	Meaning
open	In progress
resolved	Resolved
pending	Pending bot/agent handling
snoozed	Snoozed
closed	Closed (archived)

State Transition Matrix (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`

Key Constraints

resolved is the only prerequisite state for entering closed: open, pending, and snoozed cannot be set directly to closed; they must first transition to resolved before being archived.
closed can only transition back to open: Archived conversations cannot directly transition to other active states such as resolved, pending, or snoozed.
Setting the same status is idempotent: If the target status equals the current status, validation is skipped and success is returned directly. No callback is triggered.
Validation is implemented at the ActiveRecord model layer through validate :status_transition_allowed, if: :will_save_change_to_status?, and applies to all save!, update!, and status= + save paths.

Response

Success Response

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
  }
}

This code block in the floating window

Response Parameters

Field	Type	Description
success	boolean	Return value of `save`; `true` if the status update succeeds.
conversation_id	integer	The conversation's `display_id` (account-visible ID).
current_status	string	The conversation status after the update.
snoozed_until	integer / null	The currently effective snooze expiration timestamp; always `null` when the status is not `snoozed`.

Error Responses

HTTP Status Code	Trigger Condition
401	Unauthenticated or authentication failed
403	The current user does not have access to the inbox to which the conversation belongs
404	No conversation with the corresponding `display_id` can be found under the current account
422	`status` is not a valid enum value, `snoozed_until` fails to parse, or the target status violates the STATUS_TRANSITIONS matrix

422 Response Structure

Violates the state transition matrix (comes from model-layer validation and is rendered as full_messages by RequestExceptionHandler):

{ "message": "Status can't transition from open to closed", "attributes": ["status"] }

              
              {
  "message": "Status can't transition from open to closed",
  "attributes": ["status"]
}

This code block in the floating window

Unknown status enum value (comes from 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)"
}

This code block in the floating window

Invalid snoozed_until (comes from CustomExceptions::Conversation::InvalidSnoozedUntil):

{ "message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)" }

              
              {
  "message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)"
}

This code block in the floating window