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

Node Trigger — eventos

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

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 Webhook 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 Webhook 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, mensagens ou quaisquer dados. Enquanto desativado, a Fiwano continua armazenando as mensagens recebidas, mas não as repassa; reative para retomar.
• 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 Webhook 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.