WhatsApp no n8n: enviar e receber mensagens com HTTP Request e webhook
Use a API de WhatsApp no n8n: envie mensagens com o nó HTTP Request, receba eventos no nó Webhook e valide a assinatura HMAC num nó Code.
Você já tem o fluxo desenhado no n8n: uma linha nova na planilha, um pedido pago, uma consulta marcada para amanhã. Falta a última etapa, que é justamente a que o cliente vê: a mensagem no WhatsApp. E, do outro lado, quando o cliente responde, a resposta precisa entrar no mesmo fluxo, e não ficar parada no celular de alguém.
A boa notícia é que o n8n já tem tudo o que é preciso. A apiwpp é uma API HTTP comum: enviar é uma requisição POST, e receber é um POST que a apiwpp faz para o seu n8n a cada evento. Não existe um nó nativo da apiwpp no n8n, e ele não faz falta. Dois nós que vêm com qualquer instalação resolvem: HTTP Request para enviar e Webhook para receber.
Este tutorial monta os dois lados: a credencial com a chave de API, o corpo JSON do envio com expressões e clientRef, o workflow de recebimento com filtro por tipo de evento e a validação da assinatura HMAC num nó Code, para que ninguém consiga injetar eventos falsos no seu fluxo.
O que você precisa antes de abrir o n8n
A integração usa só peças genéricas do n8n. Esta tabela resume quem faz o quê:
| Parte do fluxo | Nó do n8n | Rota ou recurso da apiwpp |
|---|---|---|
| Autenticação | Credencial Header Auth | Chave de API com escopo messages:send |
| Enviar texto, mídia, localização ou template | HTTP Request | POST /connections/{id}/send |
| Receber mensagens e status | Webhook | O endereço de webhook do projeto |
| Verificar que o evento veio da apiwpp | Code | Assinatura X-Sales-Signature (HMAC-SHA256) |
| Separar os tipos de evento | Switch ou If | Campo type do envelope |
Do lado da apiwpp, você precisa de três coisas:
- Um projeto, com uma chave de API. A chave tem escopos: para o n8n que só envia,
messages:sendbasta. A página de projetos e chaves de API explica como separar uma chave por sistema. - Um número conectado ao projeto, por QR code ou código de pareamento. O envio só é aceito com a conexão no status
open. - O id da conexão, que vai na URL de envio. Ele aparece no painel e também chega em todo evento, no campo
connectionId.
Se você ainda está decidindo se uma API de WhatsApp é o caminho certo para o seu caso, o guia API de WhatsApp: o que é e quando usar dá o contexto antes da mão na massa.
Crie a credencial Header Auth com a chave de API
Guardar a chave numa credencial, e não colada no nó, tem duas vantagens: ela fica criptografada no banco do n8n e não aparece quando você exporta ou compartilha o workflow.
No n8n, vá em Credentials, crie uma credencial do tipo Header Auth e preencha:
| Campo | Valor |
|---|---|
| Name | Authorization |
| Value | Bearer wag_live_... (a sua chave, com a palavra Bearer e um espaço antes) |
A apiwpp também aceita a chave no cabeçalho X-Api-Key. Nesse caso, o Name é X-Api-Key e o Value é só a chave, sem Bearer. Escolha um dos dois e mantenha.
Quando precisar trocar a chave, a apiwpp permite rotacionar com uma janela em que a antiga e a nova funcionam juntas: você atualiza a credencial no n8n dentro dessa janela e nenhum envio falha no meio da troca.
Envie mensagens com o nó HTTP Request
Adicione um nó HTTP Request depois do gatilho do seu fluxo (planilha, formulário, banco, agendamento) e configure:
- Method:
POST - URL:
https://api.apiwpp.com/connections/SEU_CONNECTION_ID/send - Authentication:
Generic Credential Type, com Generic Auth TypeHeader Authe a credencial criada acima - Send Body: ligado, com Body Content Type
JSONe Specify BodyUsing JSON
O corpo JSON com expressões do n8n
O corpo leva o destinatário em to e o conteúdo em um destes campos: message (texto), media, location ou template. Um exemplo que usa os dados do item anterior do fluxo:
{
"to": "{{ String($json.telefone).replace(/\D/g, '') }}",
"message": {{ JSON.stringify('Olá, ' + $json.nome + '! Seu pedido ' + $json.pedido + ' saiu para entrega.') }},
"clientRef": "pedido-{{ $json.pedido }}-enviado",
"typingDelay": 2000
}
Três detalhes desse corpo evitam os erros mais comuns:
- O telefone só com dígitos, com código do país e DDD, como
5511988887777. Oreplacetira parênteses, traços e espaços que costumam vir de planilhas e formulários. Você não precisa se preocupar com o nono dígito: antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço o número está registrado. - O texto com
JSON.stringify, sem aspas em volta. Se você escrever"message": "{{ $json.texto }}"e o texto tiver aspas ou uma quebra de linha, o JSON quebra e o nó falha. OJSON.stringifyescapa tudo e já devolve a string entre aspas. - O
typingDelaymostra "digitando…" por alguns milissegundos antes da mensagem (o padrão é 1500). É opcional.
Para enviar um arquivo, troque message por media, com uma URL https pública. Um boleto em PDF, por exemplo:
{
"to": "{{ String($json.telefone).replace(/\D/g, '') }}",
"media": {
"type": "document",
"url": "{{ $json.boletoUrl }}",
"mimetype": "application/pdf",
"fileName": "boleto-{{ $json.pedido }}.pdf",
"caption": "Segue o seu boleto."
},
"clientRef": "boleto-{{ $json.pedido }}"
}
clientRef: o nó pode repetir sem duplicar a mensagem
O clientRef é a peça mais importante do corpo, e no n8n ele pesa ainda mais. Um workflow pode rodar de novo por vários motivos: você reexecuta uma execução com erro, liga o Retry On Fail nas configurações do nó, ou o gatilho entrega o mesmo item duas vezes. Sem proteção, o cliente recebe a mesma mensagem duas vezes.
Com clientRef, a apiwpp reconhece a repetição: um segundo envio com o mesmo valor responde 200 com o job original e "duplicate": true, sem colocar nada na fila. A referência fica reservada por 7 dias e aceita até 200 caracteres.
A regra para escolher o valor é derivá-lo do dado de negócio, nunca da execução. pedido-4821-enviado é o mesmo em qualquer reexecução; um valor com $execution.id ou com a hora atual muda a cada tentativa e não protege nada. O recurso de idempotência com clientRef e o guia sobre mensagens duplicadas aprofundam o assunto.
O que a API responde
O envio não acontece na hora: a apiwpp coloca a mensagem na fila do número e responde 202 em seguida:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
scheduledAt é quando o envio está previsto, em milissegundos unix, e position é o lugar na fila. Guarde o jobId se quiser cancelar o envio depois, com DELETE /connections/{id}/queue/{jobId}.
As respostas de erro que valem tratar no fluxo:
| Status | Quando acontece | O que fazer no n8n |
|---|---|---|
400 | A conexão não está open, ou falta conteúdo no corpo | Pare o fluxo e avise alguém: reconectar é uma ação humana |
401 ou 403 | Chave errada, revogada ou sem o escopo | Confira a credencial |
429 com new_recipient_cap_reached | O número já falou com o máximo de destinatários novos em 24 horas | Leia o cabeçalho Retry-After e tente depois; nada foi enfileirado |
Para tratar esses casos sem derrubar o workflow inteiro, use nas configurações do nó a opção On Error com a saída de erro e ligue ao ramo de erro um aviso por e-mail, Slack ou uma linha numa planilha de pendências.
Receba eventos com o nó Webhook
Enviar é metade do trabalho. A outra metade é saber que a mensagem foi entregue e lida, que o cliente respondeu, que o número caiu. A apiwpp avisa tudo isso com um POST por evento para o endereço de webhook do projeto, e o nó Webhook do n8n é exatamente um endereço que recebe POST.
Configure o nó Webhook
Crie um workflow novo, só para os eventos da apiwpp, começando por um nó Webhook:
- HTTP Method:
POST - Path: algo difícil de adivinhar, como
apiwpp-eventos-7f3k9 - Respond:
Immediately, para responder na hora - Options → Raw Body: ligado. Isso guarda o corpo exatamente como chegou, em bytes, que é o que a validação da assinatura precisa
O Respond: Immediately importa porque a apiwpp espera um 2xx em até 10 segundos. Se o seu fluxo consulta um CRM, gera um PDF ou chama outra API antes de responder, ele passa desse prazo, a entrega conta como falha e o evento é reenviado.
O n8n mostra duas URLs no nó. A Test URL só funciona enquanto você clica em "Listen for test event" no editor; a Production URL funciona com o workflow ativado. Use a de teste para desenvolver e troque pela de produção quando ativar.
Aponte o projeto para o n8n
O endereço de webhook é do projeto, e todos os números do projeto enviam para ele. Ele precisa ser uma URL https pública que responde direto, sem redirecionamento. Se o seu n8n roda na sua máquina, exponha-o com um túnel https durante os testes.
Defina o endereço e um segredo de assinatura numa chamada só, com uma chave que tenha o escopo webhooks:write:
WEBHOOK_SECRET=$(openssl rand -hex 32)
curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d "{\"webhookBaseUrl\": \"https://n8n.suaempresa.com.br/webhook/apiwpp-eventos-7f3k9\", \"webhookSecret\": \"$WEBHOOK_SECRET\"}"
Guarde o segredo antes de enviá-lo: a API nunca o devolve, só responde "hasWebhookSecret": true.
Cada evento chega no mesmo envelope, com type, connectionId, tenantId, externalId, timestamp e data. O tutorial de webhooks do WhatsApp detalha cada campo e cada tipo de evento; a lista completa também está na página de webhooks assinados.
Valide a assinatura HMAC num nó Code
A URL do Webhook é pública. Sem validação, qualquer pessoa que descubra o endereço consegue disparar o seu fluxo com um evento inventado, por exemplo uma "mensagem recebida" que aciona uma resposta automática ou cria um lead falso no CRM.
Com o segredo definido, cada entrega traz dois cabeçalhos: X-Sales-Timestamp, com os segundos unix da tentativa, e X-Sales-Signature, com sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto. O n8n entrega os cabeçalhos em letras minúsculas, em $json.headers.
Logo depois do Webhook, adicione um nó Code em JavaScript, no modo Run Once for All Items:
const crypto = require('crypto');
const SECRET = $env.APIWPP_WEBHOOK_SECRET;
// Sem segredo não há o que verificar: falhe em vez de aceitar tudo
if (!SECRET) throw new Error('APIWPP_WEBHOOK_SECRET não está definido');
const items = $input.all();
const verified = [];
for (let i = 0; i < items.length; i++) {
const headers = items[i].json.headers ?? {};
const timestamp = String(headers['x-sales-timestamp'] ?? '');
const signature = String(headers['x-sales-signature'] ?? '');
// Recusa assinaturas ausentes e timestamps a mais de 300 s do relógio
const fresh = /^\d+$/.test(timestamp) && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!fresh || !signature) continue;
// O corpo bruto, guardado pela opção Raw Body do nó Webhook
const rawBody = await this.helpers.getBinaryDataBuffer(i, 'data');
const mac = crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex');
const expected = Buffer.from(`sha256=${mac}`);
const received = Buffer.from(signature);
if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) continue;
// Daqui em diante, $json é o envelope do evento: type, connectionId, data...
verified.push({ json: JSON.parse(rawBody.toString('utf8')) });
}
return verified;
O que esse código garante:
- Assinatura sobre o corpo bruto. O HMAC é calculado sobre os bytes que chegaram. Recalcular a partir de
$json.body, que o n8n já converteu em objeto, muda espaços e ordem, e a assinatura não confere. - Comparação em tempo constante, com
timingSafeEqual, para não vazar informação pelo tempo de resposta. - Tolerância de 300 segundos, para que uma entrega capturada não possa ser repetida depois.
- Eventos inválidos somem do fluxo. O Webhook já respondeu
200, mas nada depois do Code roda para eles.
Duas configurações da sua instância podem ser necessárias. No n8n self-hosted, o require('crypto') só funciona com a variável NODE_FUNCTION_ALLOW_BUILTIN=crypto no ambiente. E o $env depende de o acesso a variáveis de ambiente estar liberado para os nós; se a sua instância bloqueia esse acesso, a alternativa é escrever o segredo direto no nó, sabendo que ele passa a fazer parte do workflow exportado.
Filtre por type e responda automaticamente
Com o evento verificado, o fluxo decide o que fazer conforme o type. Um nó Switch com uma regra por tipo resolve:
| Regra do Switch | Valor de $json.type | Destino típico |
|---|---|---|
| 1 | message.incoming | Resposta automática, CRM, abrir ticket |
| 2 | message.delivery | Atualizar o status da mensagem na sua base |
| 3 | message.send_failed | Marcar o envio como falho, com data.reason |
| 4 | connection.status | Avisar a equipe quando data.willReconnect for false |
Deixe a saída de "nenhuma regra" sem nada ligado. O contrato de eventos só cresce: tipos novos podem aparecer, e o fluxo deve simplesmente ignorá-los.
Resposta automática sem duplicar e sem responder a grupos
No ramo de message.incoming, o texto recebido está em data.body, e o endereço de quem escreveu está em data.jid. Antes de responder, filtre com um nó If: só siga quando data.jid não termina em @g.us. Em grupos, jid é o endereço do grupo e phone vem null, e uma resposta automática ali quase sempre é indesejada.
Depois, um nó HTTP Request igual ao de envio, com a mesma credencial, usando os dados do próprio evento:
- URL:
https://api.apiwpp.com/connections/{{ $json.connectionId }}/send, para responder pelo mesmo número que recebeu - Body:
{
"to": "{{ $json.data.jid }}",
"message": "Recebemos sua mensagem! Nosso horário de atendimento é de segunda a sexta, das 9h às 18h.",
"clientRef": "auto-resposta-{{ $json.data.raw.key.id }}"
}
O campo to aceita o JID como veio no evento, inclusive quando o remetente foi identificado só por LID e o phone ainda é null. E o clientRef usa o identificador da mensagem recebida, em data.raw.key.id: se o mesmo evento chegar duas vezes, o que acontece com entregas pelo menos uma vez, a segunda resposta é reconhecida como repetida e não sai. É a forma mais simples de deixar o workflow idempotente sem banco de dados.
Uma resposta automática a toda mensagem pode virar uma conversa sem fim com outro robô, e irrita quem já está sendo atendido. Limite a situações claras: fora do horário comercial, ou quando o texto tem uma palavra-chave. O ritmo da fila também vale aqui: entre duas mensagens para o mesmo destinatário há pelo menos 30 segundos, então a resposta pode não sair no mesmo instante.
Levar a conversa para o CRM
Para registrar a conversa em vez de responder, ligue o ramo de message.incoming ao nó do seu CRM ou a um HTTP Request para a API dele. Os campos úteis são data.phone (telefone em E.164, quando resolvido), data.body, data.timestamp e externalId, o identificador que você deu ao projeto. Mídia recebida chega em data.media.url, um link assinado e temporário: baixe o arquivo com um HTTP Request no próprio fluxo, em vez de guardar o link no CRM.
Nos ramos que não usam clientRef para se proteger de repetições, como gravar no CRM, as versões recentes do n8n oferecem no nó Remove Duplicates a opção de descartar itens já vistos em execuções anteriores, usando como chave, por exemplo, data.raw.key.id somado ao connectionId.
Os limites da fila também valem no n8n
O n8n processa itens em sequência muito rápido, e é tentador ler uma planilha de mil linhas e mandar tudo de uma vez. A apiwpp aceita as requisições, mas envia no ritmo que protege o número. Os padrões, por número:
- 3 mensagens por minuto, 60 por hora e 200 por dia, com intervalo aleatório de 3 a 8 segundos entre envios;
- 30 segundos entre duas mensagens para o mesmo destinatário;
- 100 destinatários novos por 24 horas; passar disso responde
429e não enfileira nada; - nos primeiros 14 dias depois de conectar, limites menores, que sobem por etapa, no aquecimento do número.
Na prática, isso muda duas coisas no seu workflow. Primeiro, não coloque nós Wait entre os envios para "espaçar" as mensagens: a fila já faz isso, e o scheduledAt de cada resposta diz quando cada uma sai. Segundo, um fluxo que dispara para uma lista grande de pessoas que nunca falaram com o número vai bater no teto de destinatários novos, e é bom que bata. A fila anti-bloqueio existe para reduzir o risco de restrição do número, não para acelerar campanhas frias; nada garante que um número nunca será restringido. O guia sobre como evitar o bloqueio do número mostra o que mais pesa.
Os melhores fluxos no n8n são os que falam com quem já é cliente: confirmação de pedido, lembrete de consulta, aviso de vencimento. O caso dos lembretes de agendamento junta os dois lados deste tutorial, com o lembrete saindo pelo HTTP Request e a resposta do cliente voltando pelo Webhook.
Como começar hoje
- Crie um projeto na apiwpp, conecte um número e gere uma chave de API com os escopos
messages:sendewebhooks:write. - No n8n, crie a credencial Header Auth com
AuthorizationeBearerseguido da chave. - Monte o workflow de envio com um nó HTTP Request para
POST /connections/{id}/send, o texto comJSON.stringifye umclientRefderivado do seu dado de negócio. - Crie o workflow de recebimento com um nó Webhook (
POST,Respond: Immediately, Raw Body ligado) e registre a URL de produção como endereço do projeto, junto com um segredo. - Valide a assinatura num nó Code e só então separe os eventos por
typenum Switch. - Crie sua conta na apiwpp e faça o primeiro teste mandando uma mensagem para o número conectado. Os planos por número estão em preços, e o resumo da integração fica na página de n8n.
Perguntas frequentes
Existe um nó oficial da apiwpp no n8n?
Não. A integração usa os nós HTTP Request, para enviar, e Webhook, para receber, que vêm em qualquer instalação do n8n. Como a apiwpp é uma API HTTP com JSON, esses dois nós fazem tudo o que um nó dedicado faria, e você controla cada campo do corpo.
Funciona no n8n Cloud e no n8n self-hosted?
Sim, nos dois. A única diferença costuma estar no nó Code da validação da assinatura: no self-hosted, o módulo crypto precisa ser liberado com NODE_FUNCTION_ALLOW_BUILTIN=crypto, e o acesso ao $env precisa estar permitido. O endereço do Webhook precisa ser https e público nos dois casos.
Por que a mensagem não sai no mesmo segundo em que o nó roda?
Porque a apiwpp coloca cada envio na fila do número e envia num ritmo que reduz o risco de bloqueio, com intervalos aleatórios entre as mensagens. A resposta 202 traz o scheduledAt, com o horário previsto, e a position na fila. O status real chega depois, pelo evento message.delivery.
O workflow rodou duas vezes. O cliente vai receber a mensagem repetida?
Não, se o corpo tiver um clientRef derivado do dado de negócio, como o número do pedido. Um segundo envio com o mesmo valor, em até 7 dias, responde 200 com "duplicate": true e não coloca nada na fila. Sem clientRef, cada execução gera uma mensagem nova.
Preciso validar a assinatura se o caminho do Webhook é secreto?
É altamente recomendado. Um caminho difícil de adivinhar ajuda, mas URLs aparecem em logs, prints e históricos de navegador. A assinatura HMAC prova que o evento veio da apiwpp e não foi alterado, e o limite de 300 segundos impede que uma entrega capturada seja repetida.
Dá para usar o mesmo padrão no Make ou no Zapier?
Sim. O desenho é o mesmo em qualquer ferramenta de automação: uma requisição HTTP com a chave no cabeçalho Authorization para enviar, e um gatilho de webhook para receber os eventos. As páginas de integração com o Make e o Zapier mostram os módulos equivalentes de cada uma.
Leia também: