A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channel": "email",
"subject": "<string>",
"status": "open",
"priority": "low",
"assignee_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"snoozed_until": "2023-11-07T05:31:56Z",
"first_responded_at": "2023-11-07T05:31:56Z",
"resolved_at": "2023-11-07T05:31:56Z",
"last_message_at": "2023-11-07T05:31:56Z",
"last_contact_message_at": "2023-11-07T05:31:56Z",
"first_response_due_at": "2023-11-07T05:31:56Z",
"resolution_due_at": "2023-11-07T05:31:56Z",
"sla_first_breached_at": "2023-11-07T05:31:56Z",
"sla_resolution_breached_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Update a conversation
Requires support:write. Partial: an absent field leaves the value alone, and clearing is its own flag (unassign, clear_snooze) rather than an absent field read as intent. The assignee must be a member of the organization. Moving to resolved stamps resolved_at; moving anywhere else clears it.
Each change publishes its own fact (conversation.status_changed, conversation.assigned) carrying who did it, which is what files the act in the audit trail.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channel": "email",
"subject": "<string>",
"status": "open",
"priority": "low",
"assignee_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"snoozed_until": "2023-11-07T05:31:56Z",
"first_responded_at": "2023-11-07T05:31:56Z",
"resolved_at": "2023-11-07T05:31:56Z",
"last_message_at": "2023-11-07T05:31:56Z",
"last_contact_message_at": "2023-11-07T05:31:56Z",
"first_response_due_at": "2023-11-07T05:31:56Z",
"resolution_due_at": "2023-11-07T05:31:56Z",
"sla_first_breached_at": "2023-11-07T05:31:56Z",
"sla_resolution_breached_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Path Parameters
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Body
pending is "waiting on the contact"; snoozed is the agent's own "not now".
open, pending, snoozed, resolved low, normal, high, urgent A member of this organization. Contradicts unassign.
Contradicts clear_snooze.
Response
The updated conversation.
One support thread, as staff see it. Ticket and chat are the same object — channel is the only thing that differs between an email thread and a widget chat.
The person talking.
The team they belong to, when known. An anonymous widget visitor has none.
email, chat pending means waiting on the contact — it is what a reply moves an open conversation to, and it will pause the SLA clock.
open, pending, snoozed, resolved low, normal, high, urgent Stamped once, by the first public staff reply, and never moved — the number a first-response SLA is measured against. A note does not stamp it.
When the first-response SLA clock runs out, projected over the organization's business hours. Null is a clock that is not running — no policy, paused (pending/snoozed), already answered.
When the resolution SLA clock runs out. Null under the same rule.
Stamped once by the SLA sweep, in the same transaction as conversation.sla_breached — a late answer does not clear it.