Integração n8n

O Fiwano é um node comunitário verificado do n8n — listado em n8n.io/integrations/fiwano/. Use-o para construir automações de WhatsApp, Instagram e Facebook Messenger, fluxos com agentes de IA e chatbots.

Instalação

Pelo editor do n8n (recomendado)

1. Abra o painel de nodes com + ou N
2. Pesquise por Fiwano
3. Selecione Fiwano em More from the community
4. Clique em Install

No n8n Cloud, a instalação pode precisar ser habilitada antes pelo dono da instância no Cloud Admin Panel.

Alternativa manual (npm)

Use apenas quando a instalação pelo app não estiver disponível no seu ambiente (por exemplo, um setup self-hosted restrito).

mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install n8n-nodes-fiwano
# Reinicie o n8n

Para Docker self-hosted: inclua este pacote em uma imagem n8n customizada — veja o repositório no GitHub para detalhes.

Nodes

Node Action — operações

Deactivate é uma exclusão lógica. Ela impede o canal de enviar e receber, mas preserva seu ID, seu histórico e seu slot de assinatura, para que a mesma conta Meta possa ser reconectada depois. Para liberar o slot para outro canal, desative-o e envie um Subscription ID vazio em Update — veja slots de assinatura.

Node Trigger — eventos

Inicia seu workflow para qualquer um destes eventos (filtre por tipo de evento nas configurações do node):

Message Echo entrega uma cópia de qualquer mensagem que sua equipe envia fora do Fiwano (WhatsApp Business App, caixa de entrada do Instagram, Caixa de Entrada da Página do Facebook, Meta Business Suite, outra integração), para que seu workflow veja a conversa inteira. Vem desativado por padrão — selecione-o explicitamente em Event Types. Ative Track Echo Statuses em Channel → Update (a configuração echo_statuses) para também receber delivered/read/failed dos echoes. Sempre deduplique por message_id e nunca espelhe um echo de volta para a mesma conversa. Contrato completo: Receiving Messages → message.echo.

Padrões comuns de workflow

O node Fiwano é propositalmente pequeno: ele dá ao n8n uma camada de transporte confiável para WhatsApp, Instagram DM e Facebook Messenger, e deixa a lógica do workflow para o n8n e as ferramentas que você conecta ao redor.

Quando usar a Fiwano com n8n

Use quando você quer que o n8n seja dono da automação — lógica de IA, roteamento, atualizações no CRM, memória, aprovações, escalonamento — e só precisa de uma forma limpa de receber e enviar mensagens nos canais oficiais da Meta.

Não use como motor de disparo frio em massa. WhatsApp, Instagram e Messenger têm regras de janela de mensagem e opt-in; a Fiwano segue as APIs oficiais e não contorna as políticas da Meta.

Configuração automática do webhook

O trigger pode configurar o webhook nos seus canais sozinho, sem você chamar Update manualmente. Escolha um modo de Webhook Auto-Setup e anexe uma credencial da API Fiwano. Os modos automáticos (All Active Channels / Specific Channel) precisam dela para chamar a API — se estiver faltando, a ativação falha com um erro claro. No Manual a credencial é opcional, usada apenas para ler um segredo de webhook padrão:

Os Event Types selecionados no trigger são registrados como webhook_events do canal (eventos que não se aplicam ao tipo de canal são ignorados — ex.: message.sent/message.failed no Instagram). Os canais começam sem eventos habilitados, então o auto-setup os ativa para você.

Segredo do webhook. Defina um Webhook Secret para verificar as assinaturas recebidas (HMAC-SHA256; divergências são rejeitadas com HTTP 401) e, no auto-setup, registrá-lo nos seus canais. Você pode defini-lo em dois lugares: o campo Webhook Secret do próprio trigger, ou — para reutilizar um único segredo em tudo — o campo Webhook Secret da credencial da API Fiwano. O campo do trigger tem prioridade; se estiver vazio, usa-se o segredo da credencial. Esse mesmo segredo da credencial também é usado pelas operações Exchange OAuth Code e Update quando você deixa o segredo delas vazio. Deixe ambos vazios para pular a verificação (não recomendado em produção).

Quando roda: apenas na ativação / desativação do fluxo (e quando o n8n reinicia fluxos ativos) — nunca por mensagem, portanto não adiciona custo ao processamento de mensagens. Pontos a observar:

• Desativar remove o webhook dos canais que apontam para este trigger. Isso apenas limpa a URL do webhook — não apaga o canal nem os dados existentes. Enquanto desativado, novos eventos de webhook recebidos não são repassados nem armazenados; reative para retomar a entrega.
• O All Active Channels pula canais silenciosamente. Um canal que já aponta para outra URL é deixado intacto e o fluxo ativa sem erro. Então, se um canal não estiver respondendo, verifique se o webhook dele aponta para outro lugar — limpe-o ou use Specific Channel para assumi-lo.
• Limpe antes de remover. Desative o fluxo (não apenas o exclua, e não remova a credencial antes) para o trigger conseguir limpar o webhook. Se a limpeza não rodar, um canal continua apontando para uma URL do n8n inativa — a Fiwano então registra falhas de entrega e envia e-mails até você limpá-lo (via Update ou pelo portal).
• Conectou um canal novo depois de ativar? Reative o fluxo (desligue/ligue) para o trigger configurá-lo.
• Dois fluxos All Active Channels não disputam um canal — quem reivindicar primeiro um canal livre fica com ele; o outro o deixa intacto. Para mover um canal de propósito, limpe o webhook dele ou use Specific Channel.
• Seu n8n precisa estar acessível publicamente — a Fiwano entrega webhooks pela internet na URL que o trigger registra.

Workflows de exemplo

Dois workflows prontos para importar estão no repositório no GitHub. Use-os nesta ordem:

1. Connect a Channel — gera um link de conexão Meta por canal e captura o channel_id conectado automaticamente via um callback de webhook. (Você também pode conectar canais no portal Fiwano.)
2. Universal Auto-Responder — um único trigger responde a todas as mensagens no WhatsApp, Instagram e Facebook: ecoa texto e responde a anexos com os detalhes do arquivo. O padrão de ping-pong unificado — precisa de pelo menos um canal conectado (passo 1).

Importe pelo editor (Workflows → Import from File…) ou pela CLI.