Start a conversation

POST /conversations creates a conversation with the customer’s first message. customerId is only needed here: every later call uses the conversation id.
The response is the first message. Read data.conversationId from it and store it next to your own record (an order, a ticket, a user).
Always send an idempotencyKey. If the request times out you cannot tell whether the conversation was created; with a key you can retry without risk. See Idempotency.

List conversations

Results are newest first and paged: see Pagination. Each item carries customerId, status, lastMessageAt and createdAt.

Get a conversation

GET /conversations/{conversationId} returns the conversation with its customer and whether a team member is handling it (assignmentStatus, agentName).

Close and reopen

  • Asking for the status it already has changes nothing and succeeds.
  • A customer message in a closed conversation reopens it automatically.

Following replies

Replies from your team and AI agent appear as new messages in the conversation. To show them in your app, list the messages for the conversation, and use lastMessageAt on the conversation to tell whether anything new has arrived.