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:

NameTypeDescription
statusstringopen or closed.
assigned_user_idinteger | nullHuman owner. Must be a member of the organization. null unassigns.
assigned_ai_assistant_idinteger | nullAI 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_idinteger | nullConversation pipeline. It must accept the conversation's channel (channel scope).
pipeline_stage_idinteger | nullStage of pipeline_id. null puts the thread in the Incoming column.
unread_countinteger0 marks the thread read, 1 marks it unread.
ai_context_cutstringAny 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_disabledbooleantrue makes automatic AI assignment rules skip the thread.
ai_auto_assignment_disabled_reasonstring | nullReason stored with the flag.
blockedbooleantrue ignores new incoming messages of the thread.
pinned_messagesarrayFull 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_timestring (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_id notifies 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

StatusWhen
400 Bad RequestThe 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 FoundThe conversation does not exist or was deleted.

Report an issue with this documentation

Please log in to report issues with our documentation.