Skip to main content
PATCH
Update conversation

Authorizations

Authorization
string
header
required

Access token issued by gs.service.id. Its access_identity claim carries team_sid, actor_sid and actor_type, and that team scope is authoritative.

Team-SID
string
header
required

Team scope for tokens that do not carry one. Ignored when the token already names a team.

Path Parameters

sid
string
required

Conversation sid (ub_cv_...).

Required string length: 18
Pattern: ^ub_cv_

Body

application/json

Request body of update_conversation.

state
enum<string>

The user pair only: done closes the thread, needs_you reopens it. Every other state is pipeline-owned and answers 422 invalid_transition.

Available options:
done,
needs_you
snoozed_until
string | null

ISO 8601 UTC. Setting the clock parks the thread in state=later; null clears it and wakes the thread to needs_you. Any inbound message cancels the snooze on its own.

agent_mode_override
enum<string> | null

Per-lead autonomy. null clears the override and falls back to the automation, then the agent default. Fanned out to EVERY live thread of the same primary person. copilot_only takes over: pending autopilot steps are re-parked as awaiting_approval.

Available options:
autopilot_ok,
copilot_only,
off
unread_count

0 marks the thread read, 1 marks it unread (2026-09-25, the legacy toggle). Any other number is a 422, and so is 1 on a thread the lead never answered (last_inbound_at null); the counter is otherwise maintained by ingest.

Available options:
0

Response

update success envelope.

success
enum<boolean>
required
Available options:
true
operation
enum<string>
required
Available options:
update
item
object
required
updated_fields
string[]
required
previous_values
object
required
meta
object
required
kept_fields
string[]

The fields this write did not change because the person's own value stands on them (stamped person); read the item for what landed.