Conceitos

Integração e agente

Uma integração é o que você cria em Configurações → Integrações na Cavori. Ela reúne os agentes permitidos, a URL de webhook (opcional) e as chaves. Quem chama a API sempre age por uma integração.

O agente é o assistente de IA configurado na plataforma (instruções, conhecimento, comportamento). Na API ele aparece como modelo: model: "agent:<id>". O GET /v1/models lista os agentes que a chave pode usar. Você não envia prompt de sistema nem ferramentas: tudo isso vem da configuração do agente.

Conversa e external_user_id

Uma conversa é uma sequência de mensagens entre uma pessoa e um agente. Ela aparece na caixa de conversas da equipe, com o selo API, como as conversas de outros canais.

O external_user_id é o id da pessoa no seu sistema (o id do usuário, do cliente ou da sessão que você já usa). Ele é a única chave de identidade:

• é único por integração, de 1 a 200 caracteres;
• abrir outra conversa com o mesmo external_user_id reaproveita o mesmo contato, o histórico de mensagens vale dentro de cada conversa, e a memória que o agente formou sobre a pessoa (fatos e resumos) atravessa as conversas;
• ids diferentes são pessoas diferentes, mesmo que mandem o mesmo nome, telefone ou e-mail.

Telefone e e-mail informados

phone e email são opcionais e servem para a equipe ver quem é a pessoa. Eles são tratados como dados informados pelo seu sistema, e não como um canal:

• Não identificam ninguém. Não são usados para achar, juntar ou separar contatos. Um telefone igual ao de alguém que fala pelo WhatsApp não une os dois contatos nem causa erro.
• Não recebem mensagens. A Cavori não envia WhatsApp, campanha nem lembrete para um telefone ou e-mail informado pela API.
• O agente não os vê. Eles não entram no contexto do agente.
• A equipe os vê no painel do contato e na conversa, com os rótulos "Telefone informado" e "E-mail", sem poder editá-los.
• O último valor vale. Ao abrir uma nova conversa para um external_user_id que já existe, phone e email diferentes substituem os anteriores. O name só preenche um contato que está sem nome: um nome diferente é ignorado, e o que a equipe editou prevalece. Nenhum desses casos dá erro.

O phone é normalizado para só dígitos e vale com 8 a 15 dígitos. Fora disso é ignorado e a chamada segue. Envie o número com o código do país (5511999999999): a Cavori não adivinha o código, e (11) 99999-9999 fica 11999999999. O email é convertido para minúsculas e precisa ter formato de e-mail, com até 254 caracteres; um e-mail inválido responde 400 invalid_request.

Quando a identidade expira

A Cavori guarda o histórico e a memória de cada external_user_id enquanto ele estiver em uso. Se há um prazo de retenção (o que o cliente da Cavori configurou ou, sem ele, o padrão da instalação), a identidade que fica parada por mais tempo que esse prazo é anonimizada, e o telefone e o e-mail informados do contato dela são apagados. O prazo conta a partir do último uso: a última conversa aberta ou a última mensagem enviada por essa identidade.

Se a pessoa voltar depois disso, o mesmo external_user_id começa do zero, como uma pessoa nova, sem o histórico e a memória anteriores.

O que acontece quando uma pessoa assume

A conversa tem um modo: AI (o agente responde), HUMAN_REQUESTED (o agente pediu uma pessoa), HUMAN (a equipe assumiu) e RESOLVED.

Quando o modo é HUMAN ou HUMAN_REQUESTED, o agente não responde. Uma chamada a POST /v1/chat/completions grava a mensagem e responde 202 com status: "WAITING_HUMAN", sem resposta de IA:

{ "id": "cm9x0execucao0002", "conversation_id": "cm9x0conversa0001", "status": "WAITING_HUMAN" }

A resposta da pessoa da equipe não vem na resposta dessa chamada. Ela chega pelos webhooks (message.created com sender: "HUMAN") e fica disponível em GET /v1/conversations/:id/messages. Sem webhook configurado, consulte as mensagens periodicamente.

O agente também pode pedir uma pessoa durante uma resposta. Nesse caso a resposta atual é entregue normalmente, e as mensagens seguintes passam a receber 202.

Conversa resolvida

Quando a equipe ou o agente resolve a conversa, o modo vira RESOLVED. Uma nova mensagem em POST /v1/chat/completions reabre a conversa: o modo volta para AI e o agente responde. Você não precisa abrir outra conversa.

Execução

Cada chamada a POST /v1/chat/completions cria uma execução (id da resposta). Ela tem um status e os créditos reservados e cobrados, e pode ser consultada em GET /v1/requests/:id.

Idempotência

As criações exigem Idempotency-Key, de 8 a 200 caracteres. Repetir a mesma chave com o mesmo conteúdo devolve o resultado da primeira chamada em vez de criar outra coisa, o que torna seguro repetir uma chamada que deu timeout. A mesma chave com outro conteúdo responde 409 conflict. Use uma chave nova para cada conversa e para cada mensagem.