Conversations

A conversation belongs to one contact and one connection. The contact links conversations across channels. The support app and your integration work with the same underlying conversation records.

First create a contact and identity. With conversations:write, call POST /api/v2/conversations:

123456{
  "contact_id": "ctc_your_contact",
  "connection_id": "conn_your_connection",
  "identity_id": "idn_your_identity",
  "metadata": { "reference": "thread-123" }
}

The identity must belong to the contact and connection. The response includes a con_ ID, status, current response owner, ownership version, and reply eligibility. Some channel settings reuse an existing conversation. LinkedIn and X Chat use imported provider threads.

Creating a conversation does not send a message or bypass provider initiation rules. Send the first message through the messages endpoint.

Use GET /api/v2/conversations with optional connection_id, contact_id, and status filters. All statuses are included unless filtered. Use limit and cursor for pagination.

With conversations:write, send a PATCH to /api/v2/conversations/{conversation_id}:

1{ "status": "resolved" }

Statuses are open, pending, resolved, and snoozed. Snoozing requires a future UTC snoozed_until timestamp. Omit metadata to keep it unchanged; send { "metadata": {} } to clear your application's metadata.

Every mutation requires Idempotency-Key. Response ownership changes use the separate handoff endpoint, with an ownership version precondition.