WhatsApp - API Oficial do Meta

O que é

Esta é a página onde você migra o WhatsApp da sua empresa do modo QR Code (Evolution) para a Cloud API oficial do Meta, a conexão direta com o WhatsApp Business que elimina o risco de o número ser bloqueado por uso automatizado. Aqui você cadastra os tokens gerados no Meta Business Manager, acompanha a saúde da conexão, mapeia os templates de mensagem aprovados pelo Meta e liga uma resposta automática para quem escrever nesse número.

Você normalmente chega aqui clicando em Configurar Meta (ou Gerenciar Meta, depois de já estar conectado) na página de Configurações do WhatsApp, ou pelo aviso mostrado no painel do WhatsApp enquanto você ainda usa a Evolution. A página é compartilhada entre o módulo de Notificações automáticas e o Inbox: se sua empresa tem qualquer um dos dois ativo, você acessa a mesma conexão Meta, porque é uma única conexão de WhatsApp por empresa.

Como usar

1. Vá em WhatsApp > Configurações e clique em Configurar Meta no card verde do topo, ou acesse /admin/whatsapp/meta diretamente.
2. No quadro azul "URL do webhook", clique em Copiar para levar esse endereço até o painel do Meta (Configuração do app → WhatsApp → Configuration → Webhook).
3. Em Credenciais do Meta, preencha:
   • Access Token - o token permanente gerado em Meta Business Manager → Configurações → Usuários do sistema → Gerar token.
   • Phone Number ID e WhatsApp Business Account ID (WABA) - ambos ficam em Meta for Developers → WhatsApp → API Setup, no campo "From".
   • Verify Token - uma senha de sua escolha que você repete no painel do Meta. Clique em Gerar para criar uma automaticamente.
   • App Secret (opcional) - se preenchido, o sistema passa a validar a assinatura de cada aviso recebido do Meta.
   • Receber mensagens via webhook - deixe marcado para as mensagens do cliente caírem no seu Viagilize; desmarque só se outro sistema (por exemplo um CRM) já está recebendo essas mensagens.
4. Clique em Salvar e testar conexão. O sistema grava os dados e tenta validar a conexão na hora.
5. Depois de conectado, o painel Status da integração aparece com o resumo de saúde. No bloco Teste de envio, digite um telefone com o código do país (ex.: 5541999999999) e clique em Enviar teste para confirmar que a conexão funciona de ponta a ponta.
6. Em Templates do Meta, clique em Sincronizar com Meta para trazer a lista de templates já aprovados na sua conta. Para cada tipo de mensagem do sistema (reserva confirmada, cobrança, lembrete de viagem etc.), escolha o template correspondente no menu ao lado e clique em Salvar mapeamento.
7. Se ainda não tem templates aprovados, clique em Submeter templates padrão para enviar os 8 modelos prontos do Viagilize direto para análise do Meta.
8. (Opcional) Em Resposta automática, ative a chave, escreva a Mensagem de resposta, ajuste as opções e clique em Salvar resposta automática.

O que você precisa saber antes

• Salvar já muda a conexão, mesmo que o teste falhe. Ao clicar em Salvar e testar conexão, o sistema grava os tokens e muda a conexão da empresa para o Meta antes de saber se eles são válidos. Se o teste falhar, você vê o aviso "Tokens salvos mas não foi possível validar a conexão" - mas a conexão já está apontada para o Meta, não mais para a Evolution. Se os tokens estiverem errados, os próximos envios automáticos (confirmação de reserva, cobrança, lembrete) podem parar de sair até você corrigir.
• Sem template mapeado, mensagem fora da janela de 24h falha. O Meta só permite texto livre dentro das 24 horas depois que o cliente mandou a última mensagem para você. Fora dessa janela, é obrigatório usar um template aprovado. Enquanto o painel Status da integração mostrar "0 templates mapeados", os envios automáticos que caem fora dessa janela simplesmente falham.
• Templates novos levam até 48h para o Meta aprovar. Ao clicar em Submeter templates padrão, os modelos são enviados para análise - eles não ficam disponíveis para uso imediatamente. Templates que já existem na sua conta não são enviados de novo.
• O teste de envio também depende da janela de 24h. Se o número de teste nunca te enviou mensagem, o teste falha com um aviso pedindo para a pessoa mandar uma mensagem primeiro ou para você aguardar a aprovação de um template.
• Voltar para Evolution exige novo QR Code. O botão Voltar para Evolution pede confirmação porque desliga a conexão com o Meta e devolve a empresa para a Evolution - só que sem sessão ativa: será preciso escanear o QR Code de novo em WhatsApp > Conectar.
• A resposta automática só funciona com o webhook configurado e o app publicado no Meta. Não basta marcar "Receber mensagens via webhook" aqui dentro: no painel do Meta, o app precisa estar publicado (fora do modo desenvolvimento) e o campo messages do webhook precisa estar inscrito, com a mesma URL e o mesmo Verify Token cadastrados nesta página.
• Mensagens de opt-out nunca disparam a resposta automática. Se o cliente escrever "PARAR", "SAIR" ou "CANCELAR", a resposta automática não é enviada, mesmo com a opção ativada.
• A resposta automática ativada exige uma mensagem preenchida. Tentar salvar com a chave ligada e o campo de texto vazio é bloqueado, tanto na tela quanto no servidor.
• Desativar "Receber mensagens via webhook" também desativa a resposta automática na prática, porque sem o webhook chegando nenhuma mensagem do cliente é recebida para disparar a resposta.

Casos especiais

Migrar de volta para a Evolution

Ao clicar em Voltar para Evolution, aparece uma confirmação avisando que a conexão com o Meta será desativada e que será preciso escanear o QR Code novamente. Os tokens do Meta continuam salvos no formulário (não são apagados), então uma futura remigração para o Meta não exige digitar tudo de novo - mas a conexão ativa da empresa volta a ser a Evolution até você conectar por QR Code de novo.

Usar outro sistema para receber as mensagens

Se sua empresa já usa outro programa (por exemplo, um CRM) recebendo as mensagens desse mesmo número, desmarque Receber mensagens via webhook. O Viagilize continua enviando normalmente (confirmações, cobranças, lembretes), só deixa de processar o que os clientes respondem.

Template ainda não aprovado aparecendo no mapeamento

Se você já tinha um template mapeado e ele ainda não apareceu na sincronização mais recente com o Meta (por exemplo, está pendente de aprovação), o menu de seleção mostra esse nome com o aviso "(não aprovado na Meta)" para você não perder a escolha enquanto aguarda.

Erros comuns e como resolver

• "Tokens salvos mas não foi possível validar a conexão" - Os dados foram gravados, mas o Meta não confirmou a conexão. Confira o Access Token (precisa da permissão whatsapp_business_messaging), o Phone Number ID e o WABA ID no Meta Business Manager, e se o webhook já foi apontado para a URL mostrada nesta página.
• "Provider não é Meta." - Aparece ao tentar sincronizar templates, enviar teste ou submeter templates padrão antes de salvar as credenciais com sucesso. Complete o passo Salvar e testar conexão primeiro.
• "Não foi possível enviar o teste..." - O número informado no teste de envio não te mandou mensagem nas últimas 24 horas. Peça para a pessoa mandar uma mensagem primeiro, ou aguarde a aprovação de um template para enviar fora da janela.
• "Mensagem de resposta automática é obrigatória quando ativada." - Você tentou salvar a resposta automática ligada sem preencher o texto. Escreva a mensagem antes de salvar.
• "Falha no envio: [erro do Meta]" - O teste de envio foi rejeitado pelo Meta. A mensagem detalha o motivo devolvido pela API (token expirado, número não verificado, limite de mensagens etc.).

Onde encontrar

• URL: /admin/whatsapp/meta
• Caminho no menu: WhatsApp > Configurações > Configurar Meta (ou Gerenciar Meta, quando já conectado)
• Permissão necessária: nenhuma permissão específica - basta ter acesso ao módulo WhatsApp
• Módulo necessário: WhatsApp Mensagens ou Inbox WhatsApp (qualquer um dos dois libera o acesso, pois é a mesma conexão)

Veja também

• WhatsApp - Configurações Gerais - escolher o provedor, ligar automações e definir horário e limite de envio
• Conectar seu WhatsApp - conectar pela Evolution via QR Code, antes ou depois de usar o Meta
• Personalizar Templates - editar o texto enviado em cada automação
• Histórico de Mensagens - conferir o que foi enviado e reenviar mensagens com falha