Conversas

POST /v1/conversations

Abre uma conversa entre uma pessoa do seu sistema e um agente. Exige o cabeçalho Idempotency-Key, de 8 a 200 caracteres.

Campo	Tipo	Obrigatório	Descrição
model	string	sim	Agente, no formato agent:<id>.
external_user_id	string	sim	Id da pessoa no seu sistema, de 1 a 200 caracteres. É a única chave de identidade.
name	string	não	Nome, de 1 a 200 caracteres. Só preenche contato sem nome.
phone	string	não	Telefone, de 1 a 40 caracteres. Normalizado para só dígitos; se não tiver de 8 a 15 dígitos, é ignorado.
email	string	não	E-mail, até 254 caracteres, convertido para minúsculas. Formato inválido responde 400 invalid_request.

Campos que não estão na tabela são recusados com 400 invalid_request.

curl https://api.cavori.com.br/v1/conversations \
  -H "Authorization: Bearer $CAVORI_API_KEY" \
  -H "Idempotency-Key: usuario-123-conversa-1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:cm9x0example0001",
    "external_user_id": "usuario-123",
    "name": "Ana Souza",
    "phone": "+55 (11) 99999-0000",
    "email": "Ana@Exemplo.com.br"
  }'

Exemplo de resposta (phone e email voltam normalizados):

{
  "id": "cm9x0conversa0001",
  "model": "agent:cm9x0example0001",
  "external_user_id": "usuario-123",
  "name": "Ana Souza",
  "phone": "5511999990000",
  "email": "ana@exemplo.com.br",
  "mode": "AI",
  "channel": "API",
  "created_at": "2026-10-28T15:00:00.000Z"
}

Telefone e e-mail

São dados informados pelo seu sistema. A Cavori os mostra para a equipe, mas não os usa para achar contatos, enviar mensagens ou compor o contexto do agente (veja Conceitos). Recomendamos enviar o telefone com o código do país; a Cavori não o adivinha.

Quando o external_user_id já existe, a nova conversa reaproveita o contato. phone e email diferentes substituem os informados antes; um name diferente é ignorado se o contato já tem nome. Nada disso gera 409.

Idempotência

Repetir a chamada com a mesma Idempotency-Key e o mesmo corpo devolve a conversa já criada. A mesma chave com outro corpo responde 409 conflict. A comparação usa o corpo como você o enviou, antes da normalização.

GET /v1/conversations/:id

Devolve uma conversa da sua integração, no mesmo formato da criação, com o mode atual.

curl https://api.cavori.com.br/v1/conversations/cm9x0conversa0001 \
  -H "Authorization: Bearer $CAVORI_API_KEY"

Campo	Descrição
id	Id da conversa. É o conversation_id das outras chamadas.
model	Agente da conversa.
external_user_id	Id da pessoa no seu sistema.
name	Nome do contato, ou null.
phone	Telefone informado, normalizado, ou null.
email	E-mail informado, ou null.
mode	AI, HUMAN_REQUESTED, HUMAN ou RESOLVED.
channel	Sempre API.
created_at	Quando a conversa foi aberta (ISO 8601).

Uma conversa que não existe, ou que pertence a outra integração, responde 404 not_found.