API de WhatsApp para n8n

O que dá para fazer com n8n e WhatsApp

• Confirmação de pedido

  Um pedido novo na loja dispara o workflow, que manda a confirmação ao cliente com número do pedido e prazo.

• Aviso de cobrança

  Um Schedule Trigger roda todo dia, busca os boletos que vencem amanhã e avisa cada cliente.

• Atendimento com triagem

  A mensagem entra pelo Webhook, um Switch separa por palavra-chave e só o que o fluxo não resolve vai para uma pessoa.

• Registro de conversa

  Toda mensagem recebida vira linha no Google Sheets ou atividade no CRM, com número, horário e texto.

Enviar mensagens pelo n8n

1. 1

   Crie a credencial

   Em Credentials, crie uma credencial do tipo Header Auth. Name: Authorization. Value: Bearer zpx_..., com a chave gerada no painel. A chave fica guardada cifrada no n8n em vez de colada em cada nó.

2. 2

   Configure o HTTP Request

   Method POST, URL https://zapixo.com.br/api/v1/messages/text. Em Authentication escolha Generic Credential Type, depois Header Auth e a credencial do passo anterior. Ligue Send Body, Body Content Type JSON, e escreva o corpo com o campo em modo Expression:

   {
     "instance": "minha-loja",
     "number": "{{ $json.telefone }}",
     "text": "Olá {{ $json.nome }}, seu pedido {{ $json.pedido }} foi confirmado."
   }

3. 3

   Limpe o número

   O número vai só com dígitos, com DDI e DDD: 5511999999999. Telefone vindo de formulário quase sempre traz espaço, traço ou parêntese. Limpe na própria expressão:

   {{ $json.telefone.replace(/\D/g, "") }}

4. 4

   Leia a resposta

   Deu certo, a API devolve { "success": true, "messageId": "..." }. Para mandar imagem, troque a URL por /api/v1/messages/media e o corpo por mediaUrl (link público do arquivo) e caption, que é opcional.

Receber mensagens no n8n

1. 1

   Crie o nó Webhook

   HTTP Method POST. O n8n gera duas URLs: a de teste só responde enquanto Listen for test event está aberto, e a de produção só responde com o workflow ativo. No Zapixo, use a de produção.

2. 2

   Cole a URL no painel

   No painel do Zapixo, abra a instância e cole a URL em Webhook de mensagens. Ela precisa começar com https://: n8n rodando em localhost não recebe nada. Durante o desenvolvimento, use a instância pública ou um túnel.

3. 3

   Leia a mensagem

   O nó Webhook entrega o corpo da requisição dentro de body. Cada mensagem chega como evento messages.upsert, no formato da Evolution API. Os campos que importam:

   {{ $json.body.event }}                      → messages.upsert
   {{ $json.body.data.key.remoteJid }}         → 5511999999999@s.whatsapp.net
   {{ $json.body.data.key.fromMe }}            → false
   {{ $json.body.data.pushName }}              → Maria
   {{ $json.body.data.message.conversation }}  → Oi, quero saber o preço

4. 4

   Responda

   Para responder, tire o sufixo do remoteJid e use o mesmo HTTP Request do envio:

   {{ $json.body.data.key.remoteJid.split("@")[0] }}

Erros comuns e como resolver

O workflow responde a si mesmo

O webhook também recebe mensagens enviadas pela própria instância, como as digitadas no celular conectado. Elas chegam com fromMe: true. Sem filtro, o bot responde à própria resposta e entra em laço. Coloque um IF logo depois do Webhook e siga só quando fromMe for false.

Mensagem de grupo misturada

Mensagem de grupo chega com remoteJid terminando em @g.us. Se o fluxo é só para conversa individual, filtre isso no mesmo IF.

Texto vazio em conversation

Resposta citando outra mensagem, ou texto com link, costuma vir em message.extendedTextMessage.text, e não em conversation. Leia os dois: {{ $json.body.data.message.conversation || ($json.body.data.message.extendedTextMessage || {}).text }}.

Erro 429 em disparo para lista

A API aceita 60 requisições por minuto por chave. Acima disso responde 429, com o header X-RateLimit-Reset dizendo quando a janela reabre. Para listas grandes, use Loop Over Items com um Wait entre os lotes e ligue Retry On Fail nas configurações do HTTP Request.

Erros 401 e 404

401: chave errada, revogada ou sem o Bearer na frente. 404: o valor de instance não bate com o nome da instância no painel.

Webhook que demora

Deixe o nó Webhook em Respond: Immediately. O Zapixo espera até 10 segundos por um 2xx e, sem resposta, tenta de novo — até 3 vezes. Workflow que só responde no fim vira mensagem duplicada.

Perguntas frequentes