Customers — ConvoMem Docs

Customers are the core identity entity in ConvoMem. All memories and conversations are scoped to a customer.

Lookup

Find a customer by email, phone, external ID, or customer ID. This is the most common way to identify a customer at the start of a conversation. The response also carries a prompt-ready context brief (see AI agents). Pass autoCreate=true to register a first-time customer.

const result = await client.coldOpen({ email: '[email protected]' })
 
if (result.found && result.customer) {
  console.log('Customer:', result.customer.id)
}

When no customer matches and autoCreate is off, the response is { "found": false, "customer": null }.

Create

Create a new customer profile. Provide at least one of email, phone, or externalId; each must be unique within your organization.

const customer = await client.createCustomer({
  name: 'Alice',
  email: '[email protected]',
})
 
console.log('Created:', customer.id)

List

List customers with pagination. Returns the people who have talked to your key's agent — someone who only ever contacted a different agent won't appear here.

const { customers, total } = await client.listCustomers({
  page: 1,
  limit: 20,
})
 
console.log(`Showing ${customers.length} of ${total} customers`)

Get

Retrieve a single customer by ID.

const customer = await client.getCustomer({
  customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12',
})
console.log(customer.name, customer.email)

Update

Update customer fields. Fields you omit are left unchanged.

metadata is replaced, not merged

Sending metadata replaces the stored metadata object as a whole. To change one key, read the customer first and send the complete object with your change applied.

const updated = await client.updateCustomer(
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { name: 'Alice Smith', metadata: { plan: 'pro', region: 'eu' } },
)

Delete

Request permanent erasure of a customer and their owned conversations and memories. Check the HTTP response before treating the request as complete.

await client.deleteCustomer({ customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' })

Permanent deletion

Successful erasure cannot be undone. If retained analytics, shared evidence, or an unexpired export cannot be safely attributed, the API returns 409 and preserves the customer's data for operator review (see the ERASURE_* codes in Errors & limits). Do not treat this conflict as success or retry it in a tight loop. Previously downloaded files and copies held by your own integrations are outside ConvoMem's deletion boundary.

Customer statistics and duplicate-profile review are dashboard workflows, not public SDK operations. The integration contract focuses on identity resolution, customer CRUD, conversation capture, recall, and handoff.

Handoff

Generate a full cross-channel briefing — conversation journey, key memories, sentiment trend, open-issue detection, and a narrative — for a human agent taking over.

See the dedicated Handoff page for the full reference.

Response fields

Field	Type	Description
`id`	string	Unique customer identifier
`name`	string	Customer name
`email`	string	Email address
`phone`	string	Phone number
`externalId`	string	External system identifier
`metadata`	object	Custom metadata
`createdAt`	string	ISO-8601 creation timestamp
`updatedAt`	string	ISO-8601 last update timestamp

What's next

Memories — browse and manage per-customer memories
Handoff — cross-channel briefings for human agent takeover
Conversations — manage and escalate conversation sessions

SDK: TypeScript · Python · Rust