Projeto de exemplo
Para ver a integração funcionando do começo ao fim, use o agente de exemplo: um sistema pequeno, de código aberto, que você publica na sua conta da Cloudflare em poucos minutos.
- Recebe as mensagens de WhatsApp, Instagram e Messenger pelo webhook, conferindo a assinatura.
- Responde com um agente de IA simples (instruções, modelo e histórico editáveis), sem precisar de chave de IA.
- Passa para uma pessoa quando o cliente pede ("atendente") ou quando alguém da equipe responde.
- Tem um painel para ler as conversas, responder como pessoa da equipe e pausar o agente em cada conversa.
- Mostra se a chave e o segredo do webhook estão certos e manda um evento de teste.
- Revenda: gera o link da página de conexão para cada cliente (com
ref), recebe o retorno assinado em/retornoe lista os clientes conectados.
Código: github.com/Atalia-IA/atalia-worker-template
Testar o fluxo inteiro
Antes, conecte uma caixa de entrada e gere a chave, como em Integração via API.
- Publique o worker. Clique em Deploy to Cloudflare, acima. A Cloudflare copia o projeto para o seu GitHub, cria o banco e publica. Informe a chave da empresa, uma senha para o painel e, no segredo do webhook, escreva
depois. - Abra o painel do worker e, na aba Conexão, copie o endereço do webhook.
- Cadastre o webhook na Atalia, em Chave e webhook, e copie o Segredo da assinatura que aparece.
- Troque o segredo no worker (Cloudflare › o worker › Configurações › Variáveis e segredos ›
ATALIA_WEBHOOK_SECRET). - Teste: clique em Enviar evento de teste no painel do worker e mande uma mensagem para o número conectado. A resposta do agente chega no seu celular e a conversa aparece no painel.
A Atalia só mostra o segredo da assinatura depois que o endereço do webhook é salvo. Por isso o worker é publicado com um valor provisório e o segredo é trocado no passo 4. Enquanto isso, a aba Conexão do worker avisa que o segredo ainda não foi configurado.
O painel do worker
Além das conversas e da conexão, o painel tem a configuração do agente e mostra quando uma pessoa assumiu a conversa.
Revenda: a página de conexão com retorno
Se a sua conta está no modo Integrar e oferecer aos meus clientes, a aba Clientes do worker mostra o endereço de retorno (https://<seu worker>/retorno) para colar na Atalia, em Página de conexão › Voltar para o seu sistema, e gera o link de cada cliente por POST /api/v1/clients. Quando o cliente conclui, o navegador volta para o worker, que confere a assinatura com o segredo do webhook, e o evento client.connected marca o cliente como conectado. Veja Voltar para o seu sistema.
Usar como base do seu sistema
O código é curto e comentado, separado em webhook, agente, conversas e painel. Os pontos mais comuns de mudança:
| Quero | Onde mexer |
|---|---|
| Dar ferramentas ao agente (consultar pedido, agenda, estoque) | src/agent.js |
| Gravar contatos e conversas no meu CRM | applyEvent em src/webhook.js |
| Responder com botões, listas ou mídia | src/atalia.js (tipos de POST /messages na referência) |
O arquivo PROMPT.md do repositório traz textos prontos para pedir essas mudanças a uma IA, e também um texto que descreve o projeto inteiro para construí-lo do zero em outra linguagem.
O texto do projeto para a IA
Se preferir que a IA escreva um sistema parecido na sua linguagem, cole este texto e troque o que está entre colchetes:
Quero construir um sistema que atende os clientes da minha empresa pelo WhatsApp usando a Atalia.
Leia a documentação da API: https://chat.atalia.com.br/docs/llms.txt
Use [Node.js com Express / Python com FastAPI / PHP / outra] e guarde os dados em [SQLite / Postgres / outro].
O sistema tem três partes:
1. Webhook (POST /webhook) que recebe os eventos da Atalia:
- confere o header X-Atalia-Signature sobre o corpo CRU, com o segredo na variável ATALIA_WEBHOOK_SECRET, e recusa evento com mais de 5 minutos;
- ignora evento repetido pelo id (evt_...);
- grava a mensagem e responde 200 em menos de 10 segundos; a resposta da IA roda depois, fora da requisição;
- message.received: grava a conversa (conversation_id, channel.id, contato) e a mensagem, e chama o agente;
- message.echo: alguém respondeu pelo app; grava e pausa o agente naquela conversa;
- message.status: atualiza a situação da mensagem enviada.
2. Agente simples:
- instruções, modelo e quantidade de mensagens no histórico configuráveis;
- usa as últimas mensagens da conversa como histórico (cliente = user, nossas respostas = assistant);
- se o cliente escrever "atendente", "humano" ou "pessoa", responde que vai chamar alguém da equipe e pausa o agente na conversa;
- foto, áudio ou arquivo: responde que por enquanto só lê texto;
- envia a resposta por POST /api/v1/messages com o conversation_id do evento, a chave na variável ATALIA_API_KEY e o header Idempotency-Key "reply-<id da mensagem recebida>";
- se outra mensagem do cliente chegou enquanto a IA pensava, não envia (a mais nova será respondida).
3. Painel protegido por senha (variável ADMIN_PASSWORD):
- lista de conversas com a última mensagem e as não lidas;
- histórico da conversa, campo para responder como pessoa da equipe (isso pausa o agente) e um botão para pausar ou religar o agente;
- tela para editar a configuração do agente;
- tela de conexão: lista os canais (GET /api/v1/channels), mostra o endereço do webhook e tem um botão que chama POST /api/v1/webhook/test.
Me explique como rodar, como publicar e como testar o fluxo inteiro. Escreva testes para a assinatura do webhook, para o evento repetido e para o pedido de atendente.
O painel tem uma senha só, a resposta da IA roda sem fila e os eventos recebidos não são apagados. O README do repositório lista esses limites e como resolver cada um antes de atender clientes de verdade.