WhatsApp - Envios Automáticos

O que é

Esta página reúne, em um único lugar, todos os envios de WhatsApp que o Viagilize dispara sozinho a partir de eventos do sistema ou crons agendados. Cada tipo de mensagem tem um toggle independente, então você escolhe exatamente o que automatizar - desde a confirmação imediata de uma reserva até a pesquisa de satisfação enviada dias depois da viagem.

O usuário chega aqui logo após conectar o número (QR Code do Evolution ou tokens do Meta Cloud API) ou sempre que quiser revisar quais mensagens estão saindo. Os toggles persistem na tabela de configuração do WhatsApp da sua empresa e passam a valer no próximo disparo do cron, sem precisar reiniciar nada.

Como usar

1. Vá em Módulos > WhatsApp Mensagens no sidebar e clique em Configurar (botão no header) - ou acesse direto /admin/whatsapp/config.
2. Confirme que a aba Automações está ativa (chave de URL #automacoes). A outra aba, Templates, controla apenas o texto das mensagens.
3. Ative os gatilhos desejados em cada bloco. Cada bloco trata de uma categoria:
   • Reservas - Confirmação de Reserva, Cancelamento de Reserva.
   • Pagamentos - Confirmação de Pagamento, Lembrete de Cobrança, Lembrete de Vencimento (com sub-opções D-7, D-3, D-1, no dia, vencidos e horário de envio).
   • Lembretes de Viagem - 1 dia antes, 3 dias antes, 7 dias antes (toggles independentes).
   • Outros - Aniversário, Pesquisa de Satisfação.
4. Defina o Limite de mensagens por hora (10 a 600, padrão 120). Mensagens acima do teto ficam na fila e saem na hora seguinte. Esse limite protege o número contra bloqueio do WhatsApp.
5. Clique em Salvar Configurações (botão verde no rodapé). O toast confirma com "Configurações salvas com sucesso!".

Gatilhos cobertos (8 tipos)

Mensagem	Quando dispara	Cron / Evento
Confirmação de Reserva	Imediato, ao confirmar uma reserva	Observer no fluxo de checkout
Cancelamento de Reserva	Imediato, ao cancelar	Observer no cancelamento
Confirmação de Pagamento	Imediato, ao confirmar pagamento	Webhook do meio de pagamento
Lembrete de Cobrança	Diário às 10:00	whatsapp:cobranca
Lembrete de Vencimento (D-7 / D-3 / D-1 / hoje / vencidos)	A cada 30 min entre 07:00 e 18:30, no horário escolhido	whatsapp:lembretes-vencimento
Lembrete de Viagem (D-1 / D-3 / D-7)	09:00, 10:00 e 11:00, com retry para quem ainda não recebeu	whatsapp:lembretes
Cartão de Embarque	Diário às 07:00 (D-X e D-0)	embarque:enviar-cartao
Aniversário	Diário às 08:00	whatsapp:aniversario
Pesquisa de Satisfação	Diário às 12:00, após a viagem	whatsapp:pesquisa-satisfacao

Casos especiais

Retry automático dos lembretes de viagem

O cron whatsapp:lembretes é agendado em três janelas (09:00, 10:00 e 11:00) e só envia para passageiros que ainda não receberam o lembrete daquele dia. Isso garante que falhas pontuais (número fora, instância caiu) sejam reabsorvidas sem ação manual.

Lembrete de Vencimento - sub-opções

Ao ativar Lembrete de Vencimento no bloco Pagamentos, abrem-se cinco toggles secundários: 7 dias antes, 3 dias antes, 1 dia antes (véspera), No dia do vencimento, Após vencidos (até 7 dias). O dropdown Horário de envio define em qual janela do dia o lote sai (07:00 a 18:00, em intervalos de 30 min). O cron roda a cada 30 min e só dispara quando bate o horário escolhido.

WhatsApp desconectado

Se o número estiver fora do ar, o cron whatsapp:verificar-conexao roda a cada 15 min (offset 7) e marca a instância como offline. Mensagens automáticas continuam sendo geradas e ficam registradas na tabela whatsapp_messages com status failed. Após reconectar, o usuário pode reenviar manualmente em WhatsApp > Mensagens ou aguardar o próximo ciclo do cron correspondente.

Provider Meta Cloud API

Quando você migra para a API Oficial do Meta (banner verde no topo da página), os mesmos toggles continuam valendo, mas cada mensagem precisa estar atrelada a um template aprovado no WABA. Sem template aprovado para o tipo (reserva_confirmada, cobranca etc.), o envio falha com "sem template mapeado". O mapeamento é feito em Gerenciar Meta > Mapeamento de Templates.

Limite por hora atingido

Quando o número de envios na janela horária estoura o Limite de mensagens por hora, o sistema enfileira o excedente e libera no próximo intervalo. Não há perda - só atraso. Recomendado 120 (equilibrado); 60 é conservador, 300 é agressivo, 600 é o teto.

Erros comuns e como resolver

• "WhatsApp não está conectado." - Causa: instância Evolution caiu ou tokens do Meta inválidos. Solução: voltar a /admin/whatsapp, escanear o QR Code de novo (Evolution) ou revalidar tokens em Configurar Meta.
• "Mensagem de resposta automática e obrigatória quando ativada." - Causa: tentou ativar auto-reply do Meta sem preencher o texto. Solução: preencher o campo de mensagem antes de salvar.
• "sem template mapeado pra este tipo de mensagem" - Causa: provider é Meta e o tipo (ex: lembrete_vencimento) não tem template aprovado mapeado. Solução: acessar Gerenciar Meta > Templates, submeter o template padrão e mapear o tipo.
• "Required parameter is missing" (no reenvio Meta) - Causa: metadata da mensagem antiga não tem todos os IDs necessários para reconstruir as variáveis do template. Solução: o sistema preenche fallback - automaticamente; se persistir, gerar um novo envio em vez de reenviar.
• Mensagens automáticas geradas mas com status failed no histórico - Causa: número do cliente inválido ou WhatsApp da sua empresa offline na hora do cron. Solução: corrigir o telefone no cadastro do cliente e usar Reenviar na linha do histórico.

Onde encontrar

• URL: /admin/whatsapp/config
• Caminho no menu: Módulos > WhatsApp Mensagens > Configurar > aba Automações
• Permissão necessária: ver o WhatsApp
• Módulo necessário: whatsapp-mensagens (uma trava de acesso + aceite dos termos whatsapp.terms)

Veja também

• WhatsApp Automático (Modulo Adicional)
• Configurações WhatsApp
• Templates WhatsApp
• Personalizar Templates
• Histórico de Mensagens WhatsApp