Integração via API
Na integração via API, a Atalia cuida da conexão com a Meta e o seu sistema cuida do atendimento. Você conecta as caixas de entrada (WhatsApp, Instagram e Messenger), envia mensagens pela API e recebe cada mensagem dos seus clientes num endereço do seu sistema, o webhook.
Neste modo a Atalia não responde ninguém sozinha: agentes de IA, fluxos e distribuição de conversas ficam desligados. Toda mensagem recebida é gravada e repassada ao seu sistema.
Veja Integrar usando uma IA. A referência completa da API está num arquivo de texto feito para assistentes como Claude, ChatGPT e Cursor lerem: llms.txt.
O projeto de exemplo é um sistema pronto para publicar na Cloudflare: recebe as mensagens, responde com um agente de IA e mostra as conversas num painel.
Os dois modos
| Modo | Para quem | O que muda |
|---|---|---|
| Integrar ao meu sistema | Empresas que têm o próprio sistema de atendimento, CRM ou ERP | Caixas de entrada, chave e webhook. Sem painel de atendimento. |
| Integrar e oferecer aos meus clientes | Softwares que querem que os clientes conectem os próprios números | Tudo do modo anterior, mais uma página de conexão com a sua marca e a lista de clientes. Veja Conectar os números dos seus clientes. |
O modo é escolhido ao criar a conta e pode ser trocado em Configurações › Conta (ou em Configurações › Detalhes da Empresa no painel completo).
Começar em três passos
- Conecte uma caixa de entrada. Antes, confira os requisitos de cada canal (portfólio na Meta, número, conta profissional). Em Caixas de Entrada, clique em Conectar canal. O WhatsApp entra pelo login do Facebook; dá para usar um número novo ou um que já está no app do WhatsApp Business (coexistência). Cada caixa de entrada conectada ocupa uma vaga do seu pacote.
- Gere a chave da API. Em Chave e webhook, clique em Gerar chave e guarde a chave no seu servidor. Ela aparece inteira uma vez só.
- Cadastre o webhook. No mesmo lugar, informe o endereço
https://do seu sistema e clique em Enviar mensagem de teste.
Cada caixa de entrada tem um ID (ch_...), que aparece em Caixas de Entrada. É ele que o seu sistema usa para enviar.
Enviar uma mensagem
curl -X POST https://chat.atalia.com.br/api/v1/messages \
-H "x-api-key: $ATALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1042-aviso" \
-d '{"channel_id":"ch_2f81a9c0d1","to":"+5511987654321","type":"text","text":"Olá! Seu pedido saiu para entrega."}'
A resposta (202) traz o ID da mensagem. O resultado da entrega (enviada, entregue, lida ou com falha) chega depois no webhook, no evento message.status.
Fora de 24 horas da última mensagem do cliente, ou antes de ele escrever, o WhatsApp só aceita template aprovado. Texto, mídia e botões voltam com o erro TEMPLATE_REQUIRED.
Receber mensagens
A cada evento a Atalia faz um POST com JSON para o seu webhook. Os principais (o formato completo de cada um, com exemplos, está em Eventos do webhook):
| Evento | Quando |
|---|---|
message.received | Um cliente mandou mensagem. Traz o texto, a mídia e o conversation_id para responder. |
message.status | Uma mensagem enviada mudou de situação: enviada, entregue, lida ou com falha. |
message.echo | Alguém respondeu pelo app (WhatsApp Business em coexistência, Instagram ou Messenger). |
channel.connected / channel.disconnected | Uma caixa de entrada foi conectada ou desconectada. |
client.connected / client.no_slot | Revenda: um cliente concluiu a conexão, ou tentou e o pacote estava cheio. |
Responda 2xx em até 10 segundos. Sem isso o evento é reenviado algumas vezes, com espera crescente. O mesmo evento pode chegar mais de uma vez: use o id (evt_...) para ignorar repetidos. Em Entregas do webhook, no painel, você vê cada evento enviado, a resposta do seu sistema e pode reenviar.
Verificar a assinatura
Todo evento chega com o header X-Atalia-Signature: t=<horário>,v1=<assinatura>. A assinatura é um HMAC-SHA256 de "<horário>.<corpo>" com o segredo que aparece em Chave e webhook › Segredo da assinatura. Calcule sobre o corpo cru, antes de ler o JSON, e recuse eventos com mais de 5 minutos.
import crypto from 'node:crypto';
function verifyAtaliaSignature(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}
Referência completa
Todas as rotas, campos, erros e eventos estão num arquivo de texto só, pensado para ser lido por pessoas e por IAs:
A integração usa a chave da empresa (atk_live_...), que só abre a API de integração (/api/v1) e continua valendo quando alguém sai da equipe. O token pessoal do Perfil é outra coisa: age em nome de uma pessoa, com o acesso dela no painel, e é documentado na Referência da API.