Fluxo n8n – Reengajamento WhatsApp (Conexão Azul) • Guia de Operação e Edição de Mensagens
Visão geral
Este fluxo do n8n busca conversas no Chatwoot, seleciona contatos no estágio CONTATO e, conforme a "idade" da última
interação, envia templates do WhatsApp (Cloud API) para reengajar. Após o disparo, registra uma nota privada na conversa
e atualiza atributos do contato no Chatwoot (ex.: ultimo_modelo, ultima_atualizacao).
Objetivo do documento: explicar como o fluxo funciona, onde alterar textos/templates, como publicar/editar templates no
WhatsApp e cuidados de operação/segurança.
Como o fluxo funciona (passo a passo)
1. Agendamento
O gatilho usa cron para rodar entre 08h e 20h, a cada 2 horas (0 8-20/2 * * *). O node é o Schedule Trigger.
Referência: n8n Schedule Trigger (timezone, ativação do fluxo, cron).
2. Coleta de conversas (Chatwoot)
- Node Campos define apikey e conta.
- Node Capturar conversas chama GET /api/v1/accounts/{account_id}/conversations com api_access_token no header e
paginação.
- Referência de API: Conversations List e Conversation Details (Chatwoot).
3. Tratamento dos dados
- Node TRATAR DADOS organiza as conversas: pega last_non_activity_message, identifica quem falou por último (empresa x
cliente), filtra somente contatos cujo sender.custom_attributes.estgio contém "CONTATO", normaliza horário e monta
um array consolidado conversations para a próxima etapa.
4. Escolha do template e montagem do payload (Meta WhatsApp)
- Node PEGAR TODOS TEMPLATES lista templates aprovados da conta WhatsApp.
- Node VERIFICAR SE DEVE ENVIAR TEMPLATE faz:
- cálculo de dias desde a última mensagem;
- escolhe o template conforme faixas (2, 3, 7, 14, 21, 28 dias);
- evita repetir o mesmo template do último envio (ultimo_modelo);
- formata telefone (DDI 55) e cria o payload no padrão WhatsApp Cloud API /v21.0/{PHONE_NUMBER_ID}/messages com
type: "template", template.name, language.code e components (HEADER/BODY/BUTTONS).
- Referências: envio de mensagens e message templates (Cloud API); componentes do template
(HEADER/BODY/FOOTER/BUTTONS) e placeholders.
5. Envio do template (WhatsApp Cloud API)
- Node SEND TEMPLATE faz POST /{PHONE_NUMBER_ID}/messages com o JSON montado.
- Referência: endpoint de mensagens da Cloud API.
6. Registro e atualização no Chatwoot
- Node CRIAR NOVA MENSAGEM cria uma nota privada na conversa com o texto do template (para auditoria).
- Node ATUALIZAR CONTATO faz PUT /api/v1/accounts/{account_id}/contacts/{contact_id} em custom_attributes
(ultimo_modelo, ultima_atualizacao).
- Referências: Create New Message e atualização de contato (Chatwoot APIs).
Onde alterar o conteúdo das mensagens
Importante: conteúdo de templates do WhatsApp não é editado livremente no código. Você seleciona qual template aprovado
enviar, e passa valores para placeholders ({{1}}, {{2}} …) nos components do template. O texto-base é gerenciado no
WhatsApp Manager (Meta Business Manager) e precisa de aprovação.
1) Alterar o mapping de templates no n8n
- Abra o node VERIFICAR SE DEVE ENVIAR TEMPLATE.
- Revise a lógica de seleção por faixa de dias (diffDays) e os nomes dos templates, por exemplo:
- >= 28: gatilho_de_escassez_contato
- >= 21: suporte_completo_contato
- >= 14: depoimento_contato
- >= 7: oportunidade_imperdivel_contato
- >= 3: tentativa_3_d2
- >= 2: tentativa_2_d1__reforo_do_interesse
- Ajuste os nomes para os templates exatamente como aprovados no WhatsApp Manager.
- Caso adicione novos templates, garanta que o node PEGAR TODOS TEMPLATES consiga listá-los e que o find(t => t.name
=== templateSelecionado) funcione.
2) Editar o texto-base de um template (WhatsApp Manager)
1. Acesse Meta Business Manager → WhatsApp Manager → Message Templates.
2. Crie/edite um template: HEADER/BODY/FOOTER/BUTTONS, defina placeholders ({{n}}) apenas onde serão preenchidos via
API.
3. Envie para aprovação. Somente templates com status APPROVED podem ser usados.
4. Após aprovado, use o name (ex.: oportunidade_imperdivel_contato) na lógica do n8n.
Observações úteis
- Templates são a única forma de enviar mensagens fora da janela de 24h.
- Você não edita o texto de um template no momento do envio; você apenas preenche os placeholders nas components.
- Ao editar um template aprovado, ele volta para revisão e fica pendente até nova aprovação. Em muitos provedores/UI,
o template pode ter limites de edição por janela de tempo.
3) Preenchendo placeholders (no n8n)
- No node VERIFICAR SE DEVE ENVIAR TEMPLATE, a função generatePayload(...) monta os components.
- Para HEADER/BODY com {{1}}, {{2}}, etc., atribua parameters do tipo TEXT na mesma ordem.
- Para botões (BUTTONS), use sub_type (ex. quick_reply) e payload/text conforme a definição do template.
- Exemplo de template.components aceitos: HEADER (IMAGE/TEXT), BODY, BUTTONS.
Como publicar um novo template (resumo operacional)
1. Crie o template no WhatsApp Manager (nome, idioma, categoria, conteúdo e placeholders).
2. Envie para aprovação e aguarde o status APPROVED.
3. No n8n, adicione o nome do novo template à lógica de seleção (node VERIFICAR SE DEVE ENVIAR TEMPLATE).
4. Faça um teste controlado (contato interno) e verifique se:
- o envio via /messages retorna 200;
- a nota privada e a atualização de atributos no Chatwoot ocorreram;
- o fluxo não repetiu o mesmo template para o mesmo contato (regra ultimo_modelo).
Regras de negócio adotadas
- Janela de 24h (WhatsApp): fora dessa janela, apenas templates aprovados podem ser enviados.
- Evitar repetição: não envia o mesmo template consecutivamente para o mesmo contato.
- Janelas por "dias sem resposta": mapeamento por diffDays escolhido para escalar o tom (reforço de interesse → prova
social → suporte → escassez). Ajuste conforme sua estratégia de marketing.
- Estágio do contato: o fluxo só age para contatos em estgio contendo "CONTATO" (ajuste esse filtro de acordo com seu
funil).
Operação segura e boas práticas
- Segredos/Tokens: não versionar tokens no fluxo; use n8n Credentials/variáveis de ambiente.
- Retentativas: configure retryOnFail e intervalos de paginação/limite de requisições.
- Idempotência: antes de enviar, verifique ultimo_modelo e, se possível, adote um echo_id/message_id único nas notas
para evitar duplicidade.
- Auditoria: mantenha as mensagens privadas no Chatwoot com resumo do que foi enviado (data, template, parâmetros).
- Consentimento: certifique-se de que há opt-in para mensagens de marketing, conforme a política de Business Messaging
do WhatsApp.
Padrões técnicos (referências rápidas)
- WhatsApp Cloud API – enviar mensagens: endpoint /v{version}/{PHONE_NUMBER_ID}/messages (template, texto, mídia,
interativos).
- WhatsApp Cloud API – templates: criação/gestão e componentes (HEADER, BODY, FOOTER, BUTTONS) com placeholders.
- Templates aprovados: só status APPROVED pode enviar; edição exige nova aprovação.
- Janela de 24h: templates podem ser usados fora da janela; mensagens não-template apenas dentro.
- Chatwoot API – conversas: listar/paginar via api_access_token.
- Chatwoot API – mensagens: criação de mensagem/nota na conversa.
- n8n – Schedule Trigger: cron, timezone e ativação do workflow.
Checklist rápido para o cliente
- Template criado e aprovado no WhatsApp Manager, com placeholders corretos.
- Nome do template idêntico no node VERIFICAR SE DEVE ENVIAR TEMPLATE.
- Placeholders mapeados na função generatePayload (ordem {{1}}, {{2}}, …).
- Teste de envio em contato interno (retorno 200; nota privada e atualização no Chatwoot).
- Tokens guardados em Credentials do n8n.
- Fluxo ativado e cron conferido no timezone correto.
Links úteis (documentação)
- WhatsApp Cloud API – Mensagens (endpoint /messages).
- WhatsApp Cloud API – Templates (criar/enviar, componentes, diretrizes).
- Janela de 24h e uso de templates (envio fora da janela).
- Política de Business Messaging (WhatsApp).
- Chatwoot – Conversations API (listar/filtrar/detalhes) e Messages API (criar mensagem).
- n8n – Schedule Trigger (cron, timezone, ativação).
Em caso de dúvidas, a Conexão Azul pode ajustar a lógica de seleção, publicar novos templates e revisar os textos para
aderência às políticas do WhatsApp e às melhores práticas de engajamento.
