Agente de IA no WhatsApp em n8n, com a resposta escrita pelo seu fluxo de trabalho
Um passo de automatização envia por POST a mensagem do cliente, assinada e com até 10 mensagens recentes do chat, para um nó Webhook do n8n. Um nó AI Agent escreve a resposta, um nó Respond to Webhook devolve {"reply": "..."} em até 20 segundos, e esse texto é enviado a partir do número do WhatsApp Business, que continua a funcionar na app. Agentes mais lentos recebem o webhook da Meta diretamente e respondem pela Graph API.
A easyCoexistence liga o número do WhatsApp Business que já usa na app à Cloud API da Meta através da Coexistence, e executa automatizações nele.
Tempo que o passo Call my webhook espera pela resposta do seu fluxo antes de falhar.
Mensagens mais recentes do chat enviadas em history, da mais antiga para a mais recente, terminando na mensagem que iniciou a execução.
Caracteres de uma resposta enviada como um único texto do WhatsApp; o que exceder é cortado.
Intervalo mínimo entre dois e-mails de falha para a mesma automatização quando um passo de webhook falha.
O que o n8n Cloud permite num nó Code, crypto e moment; o n8n self-hosted ativa crypto com NODE_FUNCTION_ALLOW_BUILTIN.
Janela de atendimento ao cliente após a última mensagem do cliente; depois dela, a Meta aceita apenas mensagens template.
Como chega uma mensagem do WhatsApp a um agente de IA no n8n?
Através de uma automatização no número. O número tem de receber as suas mensagens através da easyCoexistence (o modo «Through easyCoexistence»), para que a Meta as entregue aqui; uma automatização cujo gatilho é A message arrives e cujo passo é Call my webhook envia por POST a mensagem para o Production URL do seu n8n. O fluxo responde na mesma resposta HTTP, e o texto devolvido segue para o cliente como mensagem do WhatsApp a partir do seu número.
Antes de chamar o n8n, a execução já passou pelas proteções. Uma entrega repetida pela Meta nunca inicia uma segunda execução, uma resposta escrita na app pausa a automatização nesse chat (4 horas por predefinição), e a resposta só sai dentro de 24 horas da última mensagem do cliente. O seu fluxo decide apenas o que dizer.
O que é que a easyCoexistence envia para o nó Webhook do n8n?
Um POST em JSON com User-Agent easyCoexistence-automations/1, X-EC-Event com o valor automation.step e um cabeçalho X-EC-Signature. message contém o texto do cliente, ou um marcador como [image] com a legenda para ficheiros multimédia; uma nota de voz chega como [voice message] seguido das respetivas palavras quando está guardada uma chave da OpenAI ou da OpenRouter. history contém até 10 mensagens recentes do chat, da mais antiga para a mais recente, cada uma com uma direção: in para o cliente, out para a resposta de uma automatização e echo para uma pessoa que escreve a partir do telemóvel. Abrange as mensagens guardadas durante o período de retenção da conta (30, 90 ou 365 dias, 90 por predefinição) e só as que chegaram enquanto as mensagens do número passavam pela easyCoexistence.
Um teste feito no painel Try it do editor envia o mesmo POST com dry_run a true, um history vazio, o contacto de exemplo 15550000000 com o nome Test customer e um identificador de mensagem que começa por test_. Não é enviado nada a ninguém, mas o seu fluxo corre de facto, por isso evite efeitos secundários, como criar encomendas, quando dry_run é true.
{
"event": "automation.step",
"dry_run": false,
"automation": { "id": "b7e0c3a2-5d1f-4c8e-9a6b-2f4d8e1c7a90", "name": "Send to my system" },
"run_id": "0d9f6a41-8c2e-4b7a-a315-6e9c2b8d4f17",
"channel": {
"type": "whatsapp",
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922"
},
"connection": { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "phone": "+1 631-555-0142", "phone_number_id": "106540352242922" },
"contact": { "id": "5511987654321", "wa_id": "5511987654321", "name": "Ana Souza" },
"message": {
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"type": "text",
"text": "Do you have gluten-free bread today?",
"at": "2026-11-11T14:02:11.000Z"
},
"history": [
{ "direction": "in", "text": "Hi! Are you open today?", "at": "2026-11-11T13:58:40.000Z" },
{ "direction": "out", "text": "Hi Ana! Yes, until 8 pm.", "at": "2026-11-11T13:58:45.000Z" },
{ "direction": "in", "text": "Do you have gluten-free bread today?", "at": "2026-11-11T14:02:11.000Z" }
]
}Como verifica a assinatura no n8n?
Acrescente um nó Code logo a seguir ao nó Webhook. X-EC-Signature tem a forma t=<segundos unix>,v1=<hex>, em que v1 é um HMAC-SHA256 de t, de um ponto e do corpo, com a chave Signing secret da automatização. Para a copiar, abra a automatização guardada e selecione o seu passo Call my webhook. Cada automatização tem o seu próprio segredo, e as ferramentas MCP nunca o devolvem; por isso, uma automatização criada pela sua IA ainda precisa desta cópia feita no painel. Um botão New secret substitui-o e o antigo deixa de funcionar de imediato, e só o proprietário da conta o pode ver, não um membro da equipa convidado.
Rejeite um t com mais de 5 minutos de diferença do seu relógio, compare em tempo constante e lance uma exceção em caso de falha: o fluxo então dá erro antes de Respond to Webhook, o n8n responde 500 e nada é enviado. O n8n Cloud permite o módulo crypto em nós Code; o n8n self-hosted precisa de NODE_FUNCTION_ALLOW_BUILTIN=crypto. A ação Hmac do nó Crypto com um nó IF também funciona, embora uma comparação no IF não seja de tempo constante.
// n8n Code node, mode "Run Once for Each Item", placed right after the Webhook node.
// n8n Cloud allows require('crypto'); self-hosted needs NODE_FUNCTION_ALLOW_BUILTIN=crypto.
const crypto = require('crypto');
const SECRET = 'whsec_...'; // the automation's Signing secret, from its editor page
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec($json.headers['x-ec-signature'] || '');
if (!m) throw new Error('Missing X-EC-Signature');
if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) throw new Error('Stale signature');
// The body was signed as compact JSON, which JSON.stringify rebuilds from the parsed body.
const mac = crypto.createHmac('sha256', SECRET).update(`${m[1]}.${JSON.stringify($json.body)}`).digest();
if (!crypto.timingSafeEqual(mac, Buffer.from(m[2], 'hex'))) throw new Error('Bad signature');
return { json: $json.body }; // event, dry_run, contact, message, history...Como configura o nó AI Agent e a resposta?
Dê ao nó AI Agent o texto do cliente como mensagem do utilizador e tudo o resto na mensagem de sistema: quem é a empresa, os factos que pode citar, o tom e o chat recente de history, para que uma pergunta de seguimento faça sentido. Ligue o modelo de chat que pretende, além de ferramentas como uma ferramenta HTTP Request que consulta uma encomenda.
Termine com um nó Respond to Webhook que responde com JSON e coloca o texto do agente num campo chamado reply. A easyCoexistence corta o espaço em excesso, ignora uma resposta vazia ou que não seja texto, e envia o restante como um único texto do WhatsApp com até 4,096 caracteres; por isso, peça ao modelo frases simples em vez de markdown.
AI Agent node
Prompt: Define below
Prompt (User Message): {{ $json.message.text }}
Options > System Message:
You answer WhatsApp messages for Bloom Café, 12 Baker St, open Tue to Sun 8:00 to 20:00.
Reply in 1 to 3 short sentences, in the customer's language, as plain text.
Never invent prices or stock. If unsure, say a person will reply here soon.
Recent chat, oldest first:
{{ $json.history.map(h => (h.direction === 'in' ? 'Customer: ' : 'Business: ') + h.text).join('\n') }}
Chat Model: your OpenAI, Anthropic or OpenRouter model
Tools (optional): an HTTP Request tool that looks up orders
Respond to Webhook node
Respond With: JSON
Response Body: { "reply": {{ $json.output.toJsonString() }} }O que acontece quando o fluxo é lento, falha ou não devolve nada?
Cada resultado fica registado no separador Runs da automatização, com a saída ou o erro do passo, para que veja qual destes aconteceu:
- Sem resposta em 20 segundos: o passo falha com Webhook did not answer, nada é enviado e a execução aparece como Failed.
- Um estado fora do 2xx, incluindo redireções: o passo falha com Webhook answered HTTP e o código.
- Um 2xx sem texto de resposta: a execução fica Done, o passo mostra HTTP 200, sem resposta, e o cliente não recebe nada automaticamente.
- Uma execução falhada envia-lhe um e-mail para que possa responder pessoalmente a esse cliente, no máximo um por automatização a cada 6 horas.
- Um chat a que respondeu a partir do telemóvel dentro da pausa (4 horas por predefinição, definido em Advanced) é ignorado como
human_activeantes de o n8n ser chamado. - Várias mensagens rápidas iniciam várias execuções. Um Wait de 1 minuto antes de Call my webhook responde uma só vez, porque uma mensagem mais recente que escolha a mesma automatização substitui a execução em espera.
Quando deve o n8n receber diretamente o webhook da Meta?
Quando o agente precisa de mais de 20 segundos, quando o fluxo tem de ver todos os eventos (estados, respostas no telemóvel, identificadores de multimédia), quando envia algo que nenhum passo cobre, como um Flow ou uma mensagem de catálogo, ou quando a empresa quer a importação do histórico de 6 meses, que só segue para um destino direto guardado nas 24 horas após a ligação. O modo direto desativa as automatizações do número: a Meta envia o seu próprio payload diretamente para o n8n e a easyCoexistence nunca vê as mensagens.
No n8n, use o nó Webhook simples, não o nó WhatsApp Trigger, que espera a sua própria aplicação Meta e o respetivo segredo. Ative Allow Multiple HTTP Methods para que um caminho longo e aleatório receba o GET de verificação da Meta e os POST, responda ao GET com o hub.challenge em bruto como texto, e guarde esse Production URL com um token de verificação através de set_webhook_destination. As respostas saem depois de um nó HTTP Request para o endpoint de envio, e a deduplicação, a pausa do telemóvel e a verificação das 24 horas passam a ser da sua responsabilidade.
| Call my webhook (Automations on) | Direct webhook (automations off) | |
|---|---|---|
| Who calls n8n | easyCoexistence, when the automation matches | Meta, for every event on the number |
| Time to answer | 20 seconds, reply in the response | No limit: send later through the Graph API |
| Authentication | X-EC-Signature with the automation's secret | A long random secret in the URL path |
| Guards | Dedupe, phone pause and 24-hour check built in | Yours to write |
| What n8n can send | Text in the reply; the other steps of the automation can send buttons, files and templates | Any Cloud API message type, templates included |
| History import | Not available | If saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text for your retention period (90 days by default), run logs 30 days | Nothing |
Como configurar
- Turn on automations for the numberOn the number's page, the Automations and incoming messages card shows Automations on or Direct to your server. Click Turn on automations if needed; numbers connected without a webhook URL start with automations on.
- Build and publish the workflowWebhook node (POST, Respond: Using 'Respond to Webhook' Node), Code node, AI Agent node, Respond to Webhook node. Publish or activate it and copy the Production URL.
- Create the automation, switched OffIn Automations, click New automation and pick Send to my system under Start from an example. Paste the Production URL into Webhook URL, set the switch to Off so it does not answer customers yet, and click Save.
- Copy the Signing secret into n8nSelect the Call my webhook step of the saved automation, copy Signing secret and paste it into the Code node.
- Test, then switch it OnClick Test, type a sample message in Try it and press Run test: n8n runs with dry_run true and the result shows the reply. When it reads right, switch the automation On and save.
Erros comuns
- Deixar a opção Respond do nó Webhook em Immediately. O n8n responde Workflow got started de imediato, a execução regista HTTP 200, sem resposta, e o cliente não recebe nada. Escolha Using 'Respond to Webhook' Node.
- Colar o URL de teste, o que tem /webhook-test/. Só escuta enquanto o editor espera um evento de teste; as automatizações precisam do Production URL de um fluxo publicado.
- Verificar com o segredo de reencaminhamento do número. Call my webhook é assinado com o Signing secret da própria automatização; o segredo de reencaminhamento assina apenas os eventos reencaminhados, por isso os passos genuínos falham a verificação.
- Devolver o texto noutra forma. Só um corpo JSON com um texto de nível superior chamado reply é enviado; {"output": "..."} ou um corpo text/plain é registado como sem resposta.
O seu passo Call my webhook entrega a mensagem do cliente ao n8n e devolve a resposta, com deduplicação, a pausa quando responde a partir do telemóvel e a verificação das 24 horas incluídas, sem custo extra por execução. A partir de US$ 9 por número ligado por mês, descendo até US$ 0.75 à medida que acrescenta números, com os primeiros 3 dias grátis.
Perguntas frequentes
Pode o ChatGPT ou o Claude criar esta automatização por mim?
Sim. Com o conector da easyCoexistence adicionado, peça uma automatização no seu número que envie as mensagens recebidas para o URL do seu n8n; a IA chama create_automation com um passo call_webhook e depois test_automation. Peça que a automatização seja criada desativada até o teste passar. O Signing secret não é devolvido pelo MCP, por isso copie-o da página da automatização.
O fluxo pode enviar imagens, botões ou templates?
Não pelo campo de resposta, que transporta apenas texto. Deixe antes que a automatização o faça: passos como Send a picture or file, Ask a question with buttons e Send a template podem ficar antes ou depois de Call my webhook. Para outros tipos de mensagem, envie-os a partir de um nó HTTP Request para a Cloud API, com o endpoint de envio e o token que get_api_credentials devolve, e não devolva resposta, para que o cliente não seja respondido duas vezes.
Pode um só fluxo responder a vários números?
Sim. Aponte uma automatização por número para o mesmo Production URL e ramifique por channel.phone_number_id ou automation.id. Cada automatização tem o seu próprio Signing secret, por isso escolha o segredo pelo automation.id antes de verificar a assinatura.
Funciona um n8n self-hosted?
Sim, se o seu Production URL for HTTPS público. A easyCoexistence recusa endereços http, localhost, privados e internos quando guarda o URL e de novo antes de cada chamada, e não segue redireções.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em