Contatos

Sincronize seus clientes com a Nevox usando o seu próprio ID.

Um contato é uma pessoa atendida pelo agente. Você identifica cada contato pelo seu ID, o external_id. Assim não precisa guardar IDs da Nevox no seu banco.

Em breve, a Nevox também vai juntar o mesmo contato vindo de canais diferentes quando o telefone ou o email coincidirem.

Criar ou atualizar (upsert)

PUT /v1/contacts/{external_id} · escopo contacts:write

bash

curl -X PUT https://api.nevox.ai/v1/contacts/paciente_1042 \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "phone": "+14125550123",
    "language": "pt-BR",
    "tags": ["plano-familia"],
    "metadata": { "cidade": "Orlando" }
  }'

json

{
  "id": "ctc_4hq81",
  "external_id": "paciente_1042",
  "name": "Maria Souza",
  "email": "maria@exemplo.com",
  "phone": "+14125550123",
  "language": "pt-BR",
  "tags": ["plano-familia"],
  "metadata": { "cidade": "Orlando" },
  "channels": ["api", "whatsapp"],
  "first_seen_at": "2026-09-14T18:02:00Z",
  "last_seen_at": "2026-11-03T14:30:00Z",
  "created_at": "2026-09-14T18:02:00Z",
  "updated_at": "2026-11-03T14:30:00Z"
}

Campo	Tipo	Observação
`name`	string
`email`	string
`phone`	string	Formato internacional E.164 (`+5511...`, `+1412...`)
`language`	string	`pt-BR`, `en-US` ou `es`
`tags`	string[]	Até 20
`metadata`	objeto	Até 50 chaves; valores string, número ou booleano

O agente vê name, language e tags. O metadata fica disponível para as ações e para a análise, mas não é mostrado ao agente. Não coloque informações sensíveis (diagnósticos, documentos, dados de cartão) em nenhum campo.

Ler

Endpoint	Escopo
`GET /v1/contacts/{external_id}`	`contacts:read`
`GET /v1/contacts?tag=&email=&phone=&updated_after=`	`contacts:read`
`GET /v1/contacts/{external_id}/timeline`	`analytics:read`. Veja análise.

Apagar (direito ao esquecimento)

DELETE /v1/contacts/{external_id} · escopo contacts:write

Apaga o contato e as conversas e mensagens ligadas a ele, na hora. A exclusão é definitiva. Use para atender pedidos de exclusão de dados (LGPD, CCPA).

json

{ "id": "ctc_4hq81", "deleted": true }