Ligar o WhatsApp ao n8n com a Cloud API oficial

Como chega uma mensagem do WhatsApp a um fluxo n8n?

A Meta entrega cada mensagem enviada para o número num único URL que indicar, através de um HTTP POST. Esse URL é toda a integração. Coloque um nó Webhook do n8n num URL de produção, defina-o como destino do webhook do número e o fluxo é executado a cada mensagem recebida.

O payload inclui o remetente, o texto ou a referência multimédia, um carimbo de data e hora e o id da mensagem. A partir daí, é um fluxo n8n normal: crie ramificações com base no conteúdo, procure o cliente, chame os restantes serviços que utiliza e decida se deve responder.

Como se trata de Coexistência, a mesma mensagem também fica na aplicação WhatsApp Business do telemóvel. Uma pessoa pode responder-lhe. O fluxo vê o que a pessoa enviou, e a pessoa vê o que o fluxo enviou, para que nenhuma resposta se sobreponha à outra.

{
  "from": "14155550188",
  "id": "wamid.HBgLMTQxNTU1NTAxODgVAgAS",
  "timestamp": "1758412800",
  "type": "text",
  "text": { "body": "do you have anything friday?" }
}

Como envia o fluxo uma resposta?

Com um nó HTTP Request contra a Cloud API, utilizando o phone number id e o access token do número. Ambos podem ser consultados no painel ou através do conector MCP, se preferir que um assistente os obtenha.

O que deve enviar depende do momento, e esta é a parte que costuma causar problemas. Nas 24 horas seguintes à última mensagem do cliente, o texto livre funciona e a resposta é o que o fluxo compôs. Fora dessa janela, só passa um template que a Meta já tenha aprovado. Um fluxo que envia apenas texto livre parece perfeito nos testes, porque os testes acontecem sempre segundos depois de uma mensagem, e depois deixa de funcionar no primeiro caso real durante a noite.

A estrutura robusta é uma ramificação: verifique há quanto tempo chegou a última mensagem recebida e escolha texto livre ou um template em conformidade.

O n8n também pode utilizar o conector MCP?

Sim, e o n8n distingue-se neste ponto. O seu nó MCP Client Tool liga-se a um servidor MCP remoto e suporta OAuth2, que é o necessário para o nosso servidor, permitindo que um nó AI Agent num fluxo chame diretamente as nossas ferramentas.

É importante saber isto porque a maioria das plataformas de automação não consegue fazê-lo. Make e Zapier executam os seus próprios servidores MCP e nenhum funciona como cliente, pelo que nenhum consegue chegar a um servidor de terceiros. O n8n consegue.

É útil para a parte de atuação: um nó de agente que decide enviar uma mensagem, verificar o estado de um número ou consultar o estado de aprovação de um template enquanto um fluxo está a ser executado. Não substitui o webhook, porque o MCP não tem forma de ser ativado por uma mensagem recebida.

Qual dos dois deve um fluxo utilizar?

Ambos, para partes diferentes, e essa divisão não é uma preferência.

O webhook é a forma como tudo começa. Um cliente escreve, a Meta entrega a mensagem ao seu nó Webhook e o fluxo é executado. Não existe um equivalente MCP para isto em nenhuma ferramenta, porque o protocolo funciona através de pedidos e respostas, em vez de permitir que algo lhe faça uma chamada de entrada.

O MCP Client Tool serve para um agente dentro desse fluxo agir sem ter de codificar a chamada manualmente. Se o fluxo já souber exatamente o que deve enviar, um nó HTTP Request contra a Cloud API é mais simples e tem menos pontos de falha. Se um agente estiver a decidir, o conector disponibiliza-lhe as onze ferramentas e as regras incluídas nas respetivas descrições, incluindo a janela de 24 horas.

Em que difere isto dos nós WhatsApp do n8n que já são utilizados?

A maioria das configurações WhatsApp do n8n encontradas atualmente baseia-se num gateway não oficial que inicia sessão como dispositivo ligado. É um produto diferente, com custos definidos pelo respetivo fornecedor, e coloca o número em risco, porque esse mecanismo viola os termos do WhatsApp e a Meta deteta o padrão de tráfego, não a biblioteca utilizada.

A outra opção comum é a API oficial sem Coexistência. Também é um produto diferente: funciona, mas migra o número. A aplicação WhatsApp Business deixa de funcionar nesse número e a equipa que respondia ao longo do dia tem de mudar para uma nova ferramenta. Para muitas pequenas empresas, isso não é aceitável, razão pela qual tantas acabaram por utilizar gateways não oficiais.

A Coexistência reúne o que faltava: API oficial, enquanto o telemóvel continua a funcionar.

Erros comuns

• Utilizar um URL de teste do n8n como destino do webhook. Deixa de escutar quando fecha o editor, pelo que as mensagens são entregues a lado nenhum.
• Não responder ao pedido de verificação da Meta. A Meta envia um GET com um desafio antes de entregar qualquer coisa, e um nó que não o devolva nunca recebe mensagens.
• Responder com texto livre fora da janela de 24 horas. Falha silenciosamente do ponto de vista do fluxo e apenas um template aprovado é aceite.

Perguntas frequentes

Continue a ler