Documentação Completa – Agente Aurora

1. Webhook do Agente – Guia Rápido de Uso

Este documento explica como criar um agente, enviar mensagens pelo webhook, usar limites de caracteres, permissões de entrada/saída e encerrar um atendimento.

2. Protocolo de Atendimento

Cada conversa exige um protocolo único (UUID ou similar). Use o mesmo protocolo enquanto o atendimento estiver aberto.

Ao encerrar, não reutilize.

3. Enviar Mensagem ao Webhook

Endpoint: POST /api/agente/webhook/{agente_id}

Campos principais

• protocolo – obrigatório.
• texto – opcional.
• audio – opcional (base64).
• imagem / arquivo – apenas quando enviado por canais que suportam (WhatsApp e Instagram).
• encerrar_atendimento – encerra a conversa.

Metadados opcionais do cliente

• nome_usuario
• email
• contato

Exemplo mínimo

{
  "protocolo": "123e4567-conv-01",
  "texto": "Olá, preciso de ajuda com meu pedido"
}

Exemplo completo

{
  "protocolo": "123e4567-conv-01",
  "texto": "Quero segunda via da fatura",
  "nome_usuario": "João Silva",
  "email": "[email protected]",
  "contato": "+55 11 99999-0000"
}

Resposta típica

{
  "agente_id": "...",
  "protocolo": "123e4567-conv-01",
  "conteudo_recebido": {
    "texto": "Quero segunda via da fatura",
    "usuario": {
      "nome": "João Silva",
      "email": "[email protected]",
      "contato": "+55 11 99999-0000",
      "protocolo": "123e4567-conv-01"
    },
    "limite_caracter": 500
  },
  "mensagem": "Aqui está o procedimento...",
  "anexos": ["https://exemplo.com/documento.pdf"],
  "modelo": "gpt-4o-mini",
  "audio_transcrito": null
}

4. Limite de Caracteres (limite_caracter)

Exemplo de truncamento

"conteudo_recebido": {
  "texto": "",
  "truncado": true,
  "limite_caracter": 100
}

5. Entrada de Mídia (WhatsApp e Instagram)

A entrada de mídia (áudio, imagem e arquivo) está disponível atualmente apenas para integrações via WhatsApp e Instagram.

{
  "protocolo": "123e4567-media-01",
  "imagem": "base64 ou URL",
  "texto": "Segue comprovante"
}

{
  "protocolo": "123e4567-audio-01",
  "audio": "Url ou Base64"
}

6. Retorno de Mídia (Agente → Cliente)

A mídia retornada pelo agente pode aparecer de duas formas:

• Como anexo em anexos: []
• Dentro da própria mensagem como uma URL enviada pelo modelo

O usuário pode criar sua própria lógica de tratamento da URL para identificar imagens, documentos ou links de sites.

{
  "mensagem": "Aqui está sua imagem",
  "anexos": ["https://servidor.com/arquivo.png"]
}

7. Encerrar Atendimento

{
  "protocolo": "123e4567-conv-01",
  "encerrar_atendimento": true
}

{
  "msg": "Atendimento encerrado com sucesso.",
  "protocolo": "123e4567-conv-01",
  "fim": "2025-09-29T12:34:56-03:00"
}

8. Permissões de Entrada e Saída

Entrada

[{"nome": "Áudio", "valor": true}]

Saída – filtros automáticos

• Links/URLs
• Imagens
• Documentos
• Anexos

{
  "saida_filtrada": true,
  "motivos_filtragem": ["links removidos"],
  "imagens_removidas": ["..."],
  "documentos_removidos": ["..."]
}

9. Erros Comuns

Quando ocorre erro do provedor: o agente é pausado automaticamente e a resposta inclui error_code, error_code_id e sugestao.

10. Exemplo cURL (Texto)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Origin: https://example.com" \
  http://localhost:5000/api/agente/webhook/<AGENTE_ID> \
  -d '{
    "protocolo": "test-prot-001",
    "texto": "Olá, preciso de suporte",
    "nome_usuario": "Maria"
  }'

11. Exemplo cURL (Encerrar)

curl -X POST -H "Content-Type: application/json" \
  http://localhost:5000/api/agente/webhook/<AGENTE_ID> \
  -d '{"protocolo": "test-prot-001", "encerrar_atendimento": true}'

12. Campos Opcionais (Resumo)

• Nome, email, contato
• Texto (quando só áudio)
• Audio
• Links/anexos
• limite_caracter
• status

13. FAQ Rápido

• Posso mandar só áudio? → Sim.
• Campos do cliente são obrigatórios? → Não.
• Protocolo pode ser reutilizado? → Não recomendado.
• Por que veio saida_filtrada? → Permissões de saída bloquearam algo.
• Como reativar agente pausado? → Editar e mudar status para ativo.