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 status transition matrix.

Request Method

POST

Request URL

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

Authentication

For details, see the authentication instructions 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
}'

            

Request Headers

Path Parameters

Request Body Parameters

status Enumerated Values

Status Transition Matrix (STATUS_TRANSITIONS)

Key Constraints

• resolved is the only prerequisite status for entering closed: open, pending, and snoozed cannot be changed directly to closed. They must first transition to resolved before being archived.
• closed can only return to open: An archived conversation cannot transition directly to other active statuses, such as resolved, pending, or snoozed.
• Writing the same status is idempotent: When the target status is the same as the current status, validation is skipped and the request succeeds 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= followed by save paths.

Response

Successful Response

HTTP 200:

              
              {
  "meta": {},
  "payload": {
    "success": true,
    "conversation_id": 45,
    "current_status": "resolved",
    "snoozed_until": null
  }
}

            

Response Parameters

Error Responses

422 Response Structure

Violation of the status transition matrix (from model-layer validation and rendered as full_messages by RequestExceptionHandler):

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

            

Unknown status enumerated value (from CustomExceptions::Conversation::InvalidStatus):

              
              {
  "message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)"
}

            

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

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