Skip to main content
POST
Close a conversation

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

A unique value (a UUID works) that makes retrying this request safe. A repeat with the same key and body within 24 hours returns the original response instead of acting twice; the same key with a different body is a 409 idempotency_key_reused.

Maximum string length: 255

Path Parameters

conversation_id
string
required

Unique identifier for a conversation.

Pattern: ^conv_[0-9a-f]{32}$
Example:

"conv_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

Body

application/json

Body for closing a conversation.

outcome
enum<string>
default:resolved

How a conversation ended.

resolved closes it and changes nothing else. won also marks the contact as won. spam also marks the contact as spam, which keeps the AI agent from replying to them in future.

Available options:
resolved,
won,
spam
won_reason
enum<string> | null

Only with outcome: won. Defaults to other.

Available options:
hiring_sale_success,
appointment_completed,
proposal_accepted,
contract_signed,
payment_confirmed,
service_completed,
other

Response

Successful Response

One thread with one contact on one channel.

created_at
string<date-time>
required
id
string
required

Unique identifier for a conversation.

Pattern: ^conv_[0-9a-f]{32}$
Example:

"conv_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

status
enum<string>
required

Where a conversation stands.

waiting: open, and nobody has picked it up yet — it is in a queue, or assigned to a teammate who has not accepted it. active: open and being handled, by the AI agent or by a teammate. closed: finished.

Available options:
waiting,
active,
closed
updated_at
string<date-time>
required

When anything about the conversation last changed, including who handles it and whether it is open.

channel
enum<string> | null

Platform this thread runs on, e.g. whatsapp.

Available options:
whatsapp_api,
whatsapp,
instagram,
slack,
web_widget,
botconversa
channel_id
string | null

Unique identifier for a channel.

Pattern: ^chn_[0-9a-f]{32}$
Example:

"chn_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

contact_id
string | null

Unique identifier for a contact.

Pattern: ^con_[0-9a-f]{32}$
Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

handler
Owner · object | null

Who is handling it now: the AI agent (kind: agent) or a teammate (kind: user). Null while it waits in a queue for a teammate, and once it is closed.

last_message_at
string<date-time> | null
needs_human
boolean | null

Whether a person has been asked for: the AI agent asked for one, or a teammate was assigned or took it over. It does not say who has the conversation — one routed straight to a teammate can read false — so use handler for that. Null once closed.

object
string
default:conversation
Allowed value: "conversation"
queue_name
string | null

The queue it is in while open.