Importação via API

Modalidade: Importação via API

Nesta modalidade, é o seu sistema que envia dados ao Waizer via HTTP, à medida que as conversas acontecem. Você controla o quê, quando e como os dados chegam. Sem uploads manuais nem agendamentos.

Quer entender as diferenças entre as modalidades? Veja o guia de tipos de fontes de dados.

A importação via API permite que você envie conversas de qualquer plataforma diretamente para o Waizer, sem depender de integrações nativas. É a opção ideal para chatbots customizados, plataformas proprietárias ou fluxos que exigem transformação de dados antes da análise.

Documentação técnica

Para a especificação completa de todos os endpoints, parâmetros e respostas, consulte a referência completa da API.

Quando usar a API

Use a importação via API quando:

• Seu chatbot está em uma plataforma sem integração nativa com o Waizer.
• Você precisa de controle total sobre quais dados enviar e quando.
• Quer transformar ou enriquecer os dados antes de enviá-los para análise.
• Está construindo uma pipeline de dados customizada.

Configuração

1. Gere uma chave de API

Acesse Gerenciar a organização → Chaves de API e clique em Criar nova chave.

• Dê um nome descritivo à chave (ex: "Bot Atendimento Produção").
• Defina as permissões necessárias. Veja a lista completa de escopos disponíveis em Chaves de API.
• Copie e guarde a chave gerada (ela só será exibida uma vez).

Segurança da chave de API

Nunca exponha sua chave de API em código frontend, repositórios públicos ou logs. Trate-a como uma senha. Se comprometida, apague-a imediatamente em Gerenciar a organização → Chaves de API e crie uma nova em seguida.

2. Selecione API como fonte de dados

No seu projeto, acesse Configurações e selecione API como tipo de fonte de dados. Selecione Criar integração para iniciar.

Agora você pode enviar seus dados através do endpoint da API.

---

Enviando conversas

Endpoint

POST api.analyzer.whitewall.dev/api/v1/messages/{projectId}

Headers obrigatórios

Authorization: Bearer {sua-chave-de-api}
Content-Type: application/json

Body da requisição

O body deve seguir o WCF (Waizer Conversation Format). Você pode enviar uma conversa completa ou mensagens individuais.

Enviando uma conversa completa

{
  "projectId": "proj_abc123",
  "conversa": {
    "externalId": "conversa-001",
    "messages": [
      {
        "id": "msg-001",
        "timestamp": "2024-01-15T10:00:00Z",
        "content": "Olá! Como posso ajudar?",
        "direction": "sent",
        "agentId": "welcome-flow"
      },
      {
        "id": "msg-002",
        "timestamp": "2024-01-15T10:00:15Z",
        "content": "Preciso cancelar meu pedido",
        "direction": "received"
      }
    ]
  }
}

Campos do objeto conversa

Campo	Obrigatório	Tipo	Descrição
externalId	Sim	string	ID único da conversa na sua plataforma
messages	Sim	array	Lista de mensagens da conversa

Campos de cada message

Campo	Obrigatório	Tipo	Descrição
id	Sim	string	ID único da mensagem
timestamp	Sim	ISO 8601	Data e hora da mensagem
content	Sim	string	Texto da mensagem
direction	Sim	sent | received	sent = bot; received = usuário
agentId	Não	string	Identificador do agente/fluxo
humanAssigneeId	Não	string	Nome do atendente humano (para handoff)
error	Não	string	Descrição de erro ocorrido na mensagem

Resposta de sucesso

{
  "status": "queued",
  "threadId": "internal-uuid-123",
  "message": "conversa enqueued for processing"
}

---

Boas práticas

Envio em lote

Para processar grandes volumes históricos, envie conversas em lote. Respeite um intervalo mínimo entre requisições para evitar bloqueios por limite de requisições.

Deduplicação

O campo externalId garante a deduplicação: se você enviar a mesma conversa duas vezes com o mesmo externalId, o Waizer atualizará a existente em vez de criar uma duplicata.

Quando enviar

Envie a conversa após ela ser finalizada (não durante). Conversas incompletas terão menos contexto para análise e podem gerar insights imprecisos.

---

Solução de problemas

Erro 401 Unauthorized

Verifique se o header Authorization está correto e se a chave de API não foi revogada.

Erro 404 Not Found

Confirme que o projectId existe e que a chave de API tem permissão de acesso a esse projeto.

Erro 422 Unprocessable Entity

O body da requisição tem um problema de formato. Revise os campos obrigatórios e os tipos de dados, especialmente o formato dos timestamps.

Conversas enviadas com sucesso, mas sem análise no dashboard

O processamento de IA é assíncrono e ocorre em ciclos automáticos diários. Aguarde até o próximo ciclo. Para entender o ciclo de processamento e boas práticas de backfill histórico via API, veja Processamento e boas práticas.