integração · n8n
Integração WhatsApp n8n: o node da D-API dentro dos seus workflows
Monte a integração WhatsApp n8n com o community node n8n-nodes-d-api: sessões, envio de texto e mídia, chats e contatos viram ações no workflow, e os eventos chegam no nó Webhook do próprio n8n.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Instalação pelo próprio n8n
Settings, Community Nodes, Install e o pacote n8n-nodes-d-api. No self-hosted, também por npm, com reinício do n8n.
Uma credencial, a sua API key
A credencial manda a chave no header Authorization para https://api.d-api.cloud. Nada de URL para configurar.
Envio síncrono ou assíncrono
Cada operação de mensagem tem o campo Assíncrono, que envia async na requisição e devolve o commandId na hora.
A integração WhatsApp n8n é o caminho mais curto entre uma ideia de automação e um fluxo rodando com o número do cliente. Para agências de automação, para o time de operações de um SaaS que quer testar uma régua antes de pedir sprint à engenharia, ou para quem entrega automação como serviço, o n8n já resolve gatilho, transformação de dados e integração com o resto das ferramentas. O que faltava era o WhatsApp como peça nativa. O community node n8n-nodes-d-api preenche essa lacuna com as mesmas conexões que a API REST usa.
Esta página mostra como instalar, o que o node faz e um workflow completo de atendimento, usando como exemplo uma agência que automatiza o pós-venda de lojas virtuais.
Instalar o node da D-API no n8n
O resultado é ter o WhatsApp no menu de nós em poucos minutos, sem escrever cliente HTTP.
- No n8n, abra Settings → Community Nodes.
- Clique em Install a community node e informe
n8n-nodes-d-api. - Em instalação self-hosted, a alternativa é
npm install n8n-nodes-d-apino ambiente do n8n, seguido de reinício. - Crie a credencial Credenciais D-API e cole a sua API key no campo Chave da API.
A credencial envia a chave no header Authorization, e o node fala sempre com https://api.d-api.cloud. Não há URL para preencher, o que evita o erro clássico de apontar um workflow de produção para o ambiente errado.
O que o node faz no seu workflow de WhatsApp
O node se organiza por recurso, e cada recurso tem as suas operações. As que mais aparecem em fluxos reais são estas:
| Recurso | Operações | Uso típico |
|---|---|---|
| Sessão | Criar, Listar, Obter, Obter QR Code, Obter Logs, Reiniciar, Deletar | Onboarding de um número novo, diagnóstico |
| Mensagem | Enviar Texto, Imagem, Vídeo, Áudio, Documento, Álbum, Sticker, Localização, Contato, Poll, Reação | Notificações, respostas, campanhas |
| Chat | Listar, Obter, Obter Mensagens | Contexto da conversa antes de responder |
| Contato | Verificar, Obter Avatar | Validar número antes de enviar |
Toda operação de mensagem tem o campo Assíncrono. Ligado, ele envia async na requisição: a API enfileira o envio e responde com um commandId em vez de esperar o WhatsApp. Em fluxos que disparam muitos envios seguidos, isso tira o tempo de execução do caminho crítico do workflow. Como funciona o resultado desses envios está em comandos assíncronos.
Para qualquer rota que o node ainda não cobre, o nó HTTP Request do n8n resolve com o mesmo header Authorization. A API é REST, documentada em OpenAPI 3, então interativos, etiquetas e grupos seguem disponíveis no mesmo workflow.
Receber mensagens: o nó Webhook do n8n
O envio é metade do fluxo. Para reagir quando o cliente responde, o workflow precisa receber os eventos da sessão. O node da D-API não tem gatilho próprio: os eventos chegam pelo nó Webhook nativo do n8n, e a sessão na D-API aponta para ele.
Crie um nó Webhook com método POST, copie a URL de produção e configure a sessão para entregar só o que o fluxo usa:
curl -X POST https://api.d-api.cloud/api/v1/sessions/loja-aurora/webhook-config \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"type": "per_event",
"events": {
"messages.received": {
"enabled": true,
"webhookUrl": "https://n8n.sua-agencia.com/webhook/pos-venda-aurora"
},
"connection.status": {
"enabled": true,
"webhookUrl": "https://n8n.sua-agencia.com/webhook/alertas-conexao"
}
}
}'
Cada evento chega com o envelope padrão: event, sessionId, data, timestamp e traceId. No n8n, o corpo fica em $json.body, então o texto da mensagem é {{$json.body.data.message}} e o remetente é {{$json.body.data.from.jid}}. A lista completa de eventos e campos está no catálogo de eventos de webhook.
Um workflow de pós-venda, nó por nó
A loja Aurora quer que o cliente que responde “trocar” depois da entrega receba as instruções de troca na hora, e que o time seja avisado. O workflow fica assim:
- Webhook recebe
messages.receivedda sessãoloja-aurora. - IF descarta
{{$json.body.data.fromMe}}igual atruee{{$json.body.data.is_group}}igual atrue, para o fluxo não responder ao próprio atendente nem a grupos. - IF confere se
{{$json.body.data.message.toLowerCase()}}contémtrocar. - D-API, Mensagem, Enviar Texto, com ID da Sessão
{{$json.body.sessionId}}, Telefone{{$json.body.data.from.jid.split('@')[0]}}e o texto com o passo a passo da troca. - D-API, Mensagem, Enviar Documento, com o PDF da política de troca.
- Um nó do seu canal interno avisa o time de pós-venda.
O passo 2 importa mais do que parece. Mensagens que o atendente da loja manda pelo celular chegam como messages.received com fromMe: true, e um fluxo sem esse filtro conversa consigo mesmo.
Usar {{$json.body.sessionId}} em vez de um valor fixo deixa o workflow pronto para atender várias lojas: cada sessão aponta para a mesma URL e a resposta sai pelo número que recebeu a mensagem.
Cuidados para rodar em produção
Três comportamentos da entrega pedem atenção num workflow. Cada tentativa de webhook espera até 30 segundos, e a entrega é repetida até 7 vezes com backoff exponencial. Se o workflow demora para responder, configure o nó Webhook para responder imediatamente e processar depois, ou o mesmo evento entra de novo. Respostas 404 ou 410 encerram as tentativas para aquela URL, então não desative um workflow de produção sem trocar o webhook da sessão antes.
O terceiro cuidado é a reconexão. Ligue connection.status num workflow separado, como no exemplo, e avise a loja quando chegar data.status igual a logged_out ou disconnected. No mesmo workflow, as operações Reiniciar e Obter QR Code da sessão trazem um QR novo para a loja escanear.
Quando sair do n8n e ir para código
O n8n é ótimo para validar fluxo e para automações de operação. Quando o fluxo vira recurso do produto, com centenas de clientes e regra de negócio crescendo, o mesmo desenho migra para o seu backend sem mudar nada do lado da D-API: os endpoints, os eventos e o sessionId são os mesmos. Para backends em Node, o SDK d-api-sdk traz os mesmos métodos com tipos. Quem trabalha com várias contas de cliente encontra mais contexto na página para agências de automação.
A referência de configuração do webhook por sessão está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O node tem um gatilho próprio para mensagens recebidas?
Não. Os eventos chegam pelo nó Webhook nativo do n8n. Você aponta o webhook da sessão na D-API para a URL de produção desse nó e filtra pelo campo event.
Funciona no n8n cloud e no self-hosted?
Funciona nos dois. No cloud, a instalação é pela tela de Community Nodes. No self-hosted, também dá para instalar o pacote por npm e reiniciar o n8n.
Posso usar o mesmo workflow para vários clientes?
Pode. Todo evento traz o sessionId, e o campo ID da Sessão do node aceita expressão. O workflow responde pela mesma sessão que recebeu a mensagem.
E se eu precisar de um endpoint que o node não tem?
Use o nó HTTP Request do n8n com o header Authorization e a sua API key. A API REST é a mesma que o node chama, então qualquer rota da documentação funciona assim.