Replace a conversation's status, handoff and owner
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Path Parameters
Body
REPLACES all three editable columns, and every one is required for that reason. This is the single route for what the dashboard splits into four buttons (take over, release, assign, close), because all four write these same three columns and nothing else. Splitting them made a client that wanted to close a thread and hand it back to the assistant issue two writes, with a window in between where the conversation was closed and still marked human, which is the state where nobody is answering. THE TRANSCRIPT IS NOT WRITABLE HERE. Post a reply at /api/v1/agent-conversations/{conversationId}/messages. channel, email and customer_id are refused by name: the shopper decides all three, and rewriting channel would send every later reply to the wrong platform.
closed is BOOKKEEPING, not deletion. The transcript, the owner and the handoff state all survive it and reopening restores the conversation to the merchant's inbox. It is the reversible archive this family offers instead of a destructive delete, and there is no delete on a conversation at all.
active, closed Who is REPLYING. human means the assistant STOPS ANSWERING that shopper: nothing replies until a person writes one, so setting it is a commitment rather than a label. Setting it does NOT assign the conversation to anybody, which is the one place this differs from the dashboard's take-over button: that button assigns to whoever clicked it, and an api key is not a person.
bot, human Who OWNS the conversation, by store user id, or null for nobody. Ownership, not takeover. REQUIRED AS A KEY even though its value may be null, because a full replace that dropped it would silently take the teammate who owns a thread off it and answer 200. The id is checked against this store's roster; a user from another store is a 400 invalid_assignee.
Response
Success
