Update a conversation
Partially update one conversation: open or close it, assign a human or an AI assistant, move it in a pipeline, mark it read or unread, cut the AI context, pin messages or block it. Send only the fields you want to change.
Endpoint
PATCH/conversations/:id
Body
Any writable conversation field. The common ones:
| Name | Type | Description |
|---|---|---|
status | string | open or closed. |
assigned_user_id | integer | null | Human owner. Must be a member of the organization. null unassigns. |
assigned_ai_assistant_id | integer | null | AI assistant. Must belong to the organization. null unassigns. Assigning one also resets the AI safeguards (token_limit_reached_at, token_limit_reason) and sets ai_auto_assignment_disabled to false. |
pipeline_id | integer | null | Conversation pipeline. It must accept the conversation's channel (channel scope). |
pipeline_stage_id | integer | null | Stage of pipeline_id. null puts the thread in the Incoming column. |
unread_count | integer | 0 marks the thread read, 1 marks it unread. |
ai_context_cut | string | Any non-empty value. The server sets it to the current time, clears conversation_summary and handoff_reason, and adds a "AI Context Cut" system message. The AI assistant then ignores older messages. |
ai_auto_assignment_disabled | boolean | true makes automatic AI assignment rules skip the thread. |
ai_auto_assignment_disabled_reason | string | null | Reason stored with the flag. |
blocked | boolean | true ignores new incoming messages of the thread. |
pinned_messages | array | Full list of pinned messages (max 3). Each item: message_id (required), message_type, preview (required, max 2000 chars), destination, pinned_at, pinned_by_user_id. System, tool, reaction and error messages cannot be pinned. |
next_follow_up_date_time | string (date-time) | Schedules the next AI follow-up at that time. |
organization_id and server-managed fields (last_message_*, counters, summaries) should not be sent.
Request
Move to a pipeline stage:
Assign an AI assistant and cut its context so it starts fresh:
Response
The updated conversation object.
json
Side effects
- Changing
assigned_user_idnotifies the new owner. - Pipeline and stage changes are recorded in the conversation's stage history.
- Updates can start automations with a "conversation updated" trigger (for example a stage change).
Errors
| Status | When |
|---|---|
400 Bad Request | The user or AI assistant does not belong to the organization, the pipeline is not accessible, the pipeline does not accept the conversation's channel (data.code = "PIPELINE_CHANNEL_NOT_ALLOWED"), or pinned_messages is invalid (more than 3, missing text, or a message type that cannot be pinned). |
404 Not Found | The conversation does not exist or was deleted. |
Report an issue with this documentation
Please log in to report issues with our documentation.