Capture

Overview

Capture is the primary way to send data to ConvoMem. It accepts single messages or full conversations and returns a capture ID for async processing.

The endpoint resolves customer identity, finds or creates an active conversation session, enqueues the message for memory extraction, and returns the session context. No explicit start/end lifecycle calls are required.

Single message

Send a single user message. ConvoMem will associate it with the customer and channel you specify.

cURLTypeScriptPythonRust

const result = await client.capture(
  [{ role: 'user', content: 'I need help with my order' }],
  { email: '[email protected]' },
  { channel: 'CHAT' },
)

Batch messages

Send a full conversation with multiple turns. This is useful when you want to capture both the user's message and the assistant's response in a single call.

cURLTypeScriptPythonRust

const result = await client.capture(
  [
    { role: 'user', content: 'What is my current plan?' },
    { role: 'assistant', content: 'You are on the Pro plan at $49/mo.' },
  ],
  { email: '[email protected]' },
  { channel: 'VOICE' },
)

Request body

Each message in the messages array has:

Response

Poll capture status

Use the returned captureId when your workflow must wait for memories before the next step. A capture moves through queued, processing, and completed; a terminal error is reported as failed with a stable public error message.

curl -H "X-API-Key: $CONVOMEM_API_KEY" \
  "https://api.convomem.com/api/v1/capture/$CAPTURE_ID"

const status = await client.getCaptureStatus(result.captureId)

Do not close a conversation in a second request immediately after capture. When the last turn is already known, send endConversation: true or escalate: true on the capture so ConvoMem preserves the ordering: transcript, memories, conversation state, then analysis.

Identity resolution

ConvoMem resolves customers from whichever identity field you provide. You only need to supply one:

• customerId — Direct lookup by ConvoMem UUID. Fastest and most reliable.
• externalId — Your system's identifier for the customer. ConvoMem maps it to an internal customer record.
• email — Matches by email address. Creates a new customer if no match is found.
• phoneNumber — Matches by phone number. Creates a new customer if no match is found.
• socialHandles — Matches by social handle. A leading @ and letter case are ignored, and a platform keeps the same handle on different networks apart.

When multiple fields are provided, ConvoMem resolves in the order listed above. If the customer does not exist, a new profile is created automatically.

Channel types

The channel is used for analytics and to group conversations. It does not affect how messages are processed.

Rate limit

Capture scales with your plan — from 100/min on Trial up to 2,000/min on Scale, and unlimited on Custom. Each agent gets that budget independently, so a busy support agent never eats into what your sales agent has left.

Each call enqueues background AI work. Send the new turns since the prior capture in chronological order. ConvoMem preserves legitimate repeated utterances; use a stable idempotencyKey to identify network retries instead of deduplicating message text in your integration.

See Errors & limits for the per-plan table and retry guidance.

What's next

• Memories — browse, add, and manage extracted memories
• Conversations — explicitly manage session lifecycle
• Webhooks — react to memory.captured after extraction completes
• AI agents — fire-and-forget patterns and tool definitions

SDK: TypeScript · Python · Rust