Conversations

Conversations track customer sessions across channels. An active conversation is reused for subsequent captures until it ends or times out.

Start

Begin a new conversation for a customer.

cURLTypeScriptPythonRust

const conversation = await client.startConversation(
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { channel: 'CHAT' },
)
 
console.log('Conversation:', conversation.id)
console.log('Status:', conversation.status)

List

List all conversations for a customer with pagination.

cURLTypeScriptPythonRust

const { conversations, total } = await client.listConversations(
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { page: 1, limit: 20 },
)
 
for (const conv of conversations) {
  console.log(`${conv.id}: ${conv.status} (${conv.channel})`)
}

End

End a conversation with an optional outcome. The REST endpoint returns the updated conversation; the SDK methods return nothing on success.

cURLTypeScriptPythonRust

await client.endConversation(
  '87c53d10-85f8-4447-920f-b1e847c23a1a',
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { outcome: 'resolved' },
)

Escalate

Escalate a conversation to a human agent with a reason (≤500 chars).

cURLTypeScriptPythonRust

await client.escalateConversation(
  '87c53d10-85f8-4447-920f-b1e847c23a1a',
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { reason: 'Complex billing dispute' },
)

By identity (flat routes)

When you only have an email, phone, or external ID, use POST /customers/conversations/end and POST /customers/conversations/escalate with the identity in the body. These routes resolve the customer and act on that customer's active conversation. They do not take a conversationId, and return 404 when the customer has no active conversation.

curl -s -X POST -H "X-API-Key: $CONVOMEM_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.convomem.com/api/v1/customers/conversations/end" \
  -d '{"email": "[email protected]", "outcome": "resolved"}'

The SDKs use these routes automatically when you pass no conversationId or no customerId:

await client.endConversation(null, { email: '[email protected]' }, { outcome: 'resolved' })

Response fields

Channel types

What's next

• Capture — the primary way to feed conversation turns
• Handoff — briefings for escalated conversations
• Webhooks — react to conversation.completed and conversation.escalated

SDK: TypeScript · Python · Rust