TypeScript SDK

The ConvoMem TypeScript SDK works in Node.js, Deno, Bun, and edge runtimes. Published to JSR as @optraze/convomem-sdk.

SDK version

These examples target SDK 0.3.0, released with ConvoMem v1.2.0.

Install

# npm / Node
npx jsr add @optraze/convomem-sdk
 
# pnpm
pnpm i jsr:@optraze/convomem-sdk
 
# bun
bunx jsr add @optraze/convomem-sdk
 
# deno
deno add jsr:@optraze/convomem-sdk

Initialize

import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({
  apiKey: process.env.CONVOMEM_API_KEY!, // required
  timeout: 10_000,                        // optional — ms per attempt (default 10 000)
  maxRetries: 3,                          // optional — retries on 429 / 5xx / timeout (default 3)
})

Retries wait a random delay of up to retryDelay × attempt (retryDelay defaults to 1,000 ms). They do not read the Retry-After header.

Keep keys server-side

Never expose an API key in client-side code. All ConvoMem calls should originate from your backend or an edge function. For browser widgets, use embed tokens.

Methods

Every method that operates on a customer accepts a CustomerIdentity and routes to the correct endpoint.

Memory methods

Method	Description
`capture(messages, identity, options?)`	Send conversation turns for background extraction; `endConversation` / `escalate` close the conversation after the turns are stored
`getCaptureStatus(captureId)`	Poll queued, processing, completed, or failed capture state
`coldOpen(identity, options?)`	Customer profile plus a call-opening brief, before the customer states a topic
`lookup(topic, identity, options?)`	Recall relevant memories as a ready-to-use context string
`listMemories(identity, options?)`	Page through all memories for a customer
`addMemory(content, identity, options?)`	Write a memory directly (synchronous, no extraction lag)
`updateMemory(memoryId, data, identity)`	Update content or category (requires `customerId`)
`deleteMemory(memoryId, identity)`	Delete a memory permanently (requires `customerId`)

Customer methods

Method	Description
`createCustomer(data)`	Create a new customer profile
`getCustomer(identity)`	Get a customer by any identity field
`listCustomers(options?)`	List customers with pagination and filters
`updateCustomer(identity, data)`	Update customer fields; `metadata` replaces the stored object
`deleteCustomer(identity)`	Request permanent customer erasure; unresolved retained sources can return a conflict

Conversation methods

Method	Description
`startConversation(identity, options)`	Begin a new conversation session
`endConversation(conversationId, identity, options?)`	Mark a conversation completed
`escalateConversation(conversationId, identity, options?)`	Escalate to a human agent
`listConversations(identity, options?)`	List a customer's conversation sessions

Handoff & embed

Method	Description
`getHandoff(identity, options?)`	Full cross-channel briefing for a human takeover
`routeHandoff(identity, options?)`	Resolve which destination a live transfer should go to
`createEmbedToken(identity, options?)`	Mint a short-lived, read-only browser token

Handoff destinations are configured in the dashboard. Dashboard-only analytics, exports, request logs, memory health, organization settings, entities, insights, and webhook administration are intentionally not shipped in the SDK.

Capture completion

const accepted = await client.capture(
  [{ role: 'user', content: 'I prefer email contact' }],
  { email: '[email protected]' },
)
const status = await client.getCaptureStatus(accepted.captureId)
console.log(status.status) // queued, processing, completed, or failed

Acceptance is not extraction completion. Poll with a bounded delay and timeout; do not interpret a failed or still-processing capture as an empty memory result.

To close the conversation, send the final turns with endConversation: true (or escalate: true) instead of calling endConversation() right after a capture:

await client.capture(
  [{ role: 'assistant', content: 'All sorted — anything else?' }],
  { phone: '+14155550101' },
  { channel: 'VOICE', endConversation: true, outcome: 'Refund issued' },
)

CustomerIdentity

All methods that operate on a customer accept a CustomerIdentity object. Provide at least one field:

interface CustomerIdentity {
  customerId?: string   // ConvoMem UUID — most direct
  externalId?: string   // Your CRM / system ID
  email?: string
  phone?: string        // E.164 preferred (+14155550101)
}

With customerId → path route (/customers/:id/*)
Without customerId → flat route (/customers/*?email=…) — server resolves

Error handling

import { ConvoMemApiError } from '@optraze/convomem-sdk'
 
try {
  await client.capture([...turns], { email: '[email protected]' })
} catch (err) {
  if (err instanceof ConvoMemApiError) {
    console.error(err.status, err.body) // e.g. 422, { error: '…', code: 'VALIDATION_ERROR' }
  }
}

Property	Type	Description
`status`	number	HTTP status code
`body`	unknown	Parsed response body
`url`	string	Full request URL

A request that exhausts its timeout on every attempt throws ConvoMemError.

TypeScript types

Key types exported from @optraze/convomem-sdk:

import type {
  CustomerIdentity,
  Customer,
  CustomerLookupResponse,
  Memory,
  MemoryContext,
  CaptureResponse,
  Conversation,
  HandoffResponse,
  HandoffRouteResponse,
  EmbedTokenResponse,
} from '@optraze/convomem-sdk/types'