Cavori para desenvolvedores

Tema

Começar ​

Neste passo a passo você cria uma integração, emite uma chave e troca a primeira mensagem com um agente. Você precisa de uma conta na Cavori com pelo menos um agente ativo e de um plano ativo. Sem plano ativo, toda chamada responde 402 plan_inactive.

1. Criar a integração e emitir a chave ​

No portal da Cavori, abra Configurações → Integrações e crie uma integração:

  1. Dê um nome e escolha os agentes que ela pode usar. Só esses agentes aparecem para a chave.
  2. Se quiser receber webhooks, informe a URL HTTPS do seu servidor. A Cavori mostra o segredo do webhook uma única vez, na criação ou quando a URL muda.
  3. Emita uma chave. Ela começa com cvk_ e também aparece só uma vez. Guarde-a em um cofre de segredos ou em uma variável de ambiente do seu servidor.

Nos exemplos abaixo, a chave está em CAVORI_API_KEY:

bash
export CAVORI_API_KEY="cvk_..."

2. Listar os agentes ​

A URL base é https://api.cavori.com.br.

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

Exemplo de resposta:

json
{
  "object": "list",
  "data": [
    { "id": "agent:cm9x0example0001", "object": "model", "name": "Atendimento" }
  ]
}

O id é o valor que você usa em model nas próximas chamadas.

3. Abrir uma conversa ​

Cada pessoa do seu sistema tem um external_user_id, que é o id dela aí do seu lado. A criação exige o cabeçalho Idempotency-Key, de 8 a 200 caracteres.

bash
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",
    "email": "ana@exemplo.com.br"
  }'

Exemplo de resposta:

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

Guarde o id: é o conversation_id das mensagens. name, phone e email são opcionais; veja Conversas para o que a Cavori faz com eles.

4. Enviar a primeira mensagem ​

bash
curl https://api.cavori.com.br/v1/chat/completions \
  -H "Authorization: Bearer $CAVORI_API_KEY" \
  -H "Idempotency-Key: usuario-123-turno-1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:cm9x0example0001",
    "conversation_id": "cm9x0conversa0001",
    "messages": [{ "role": "user", "content": "Olá, vocês abrem no sábado?" }]
  }'

Exemplo de resposta:

json
{
  "id": "cm9x0execucao0001",
  "object": "chat.completion",
  "conversation_id": "cm9x0conversa0001",
  "message_id": "cm9x0mensagem0002",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Abrimos sim, das 9h às 13h." },
      "finish_reason": "stop"
    }
  ]
}

Para receber a resposta aos poucos, acrescente "stream": true. O formato está em Chat completions.

Próximos passos ​

  • Entenda o que acontece quando uma pessoa da equipe assume a conversa em Conceitos.
  • Configure webhooks para receber as respostas humanas.
  • Trate os erros e respeite os limites.
  • Se a chamada vem de um site, leia Sites antes de publicar.