WhatsApp - Conectar Número

O que é

Esta e a tela inicial do modulo WhatsApp Mensagens. Aqui você pareia o número de WhatsApp da empresa ao Viagilize, gerando um QR Code que e lido pelo celular - o mesmo procedimento usado no WhatsApp Web. Após conectada, a instancia passa a enviar automaticamente confirmacoes de reserva, lembretes de viagem, cobrancas, mensagens de aniversario e demais notificações configuradas em Configurações.

A página serve como dashboard de saude da conexao: mostra status em tempo real (Conectado, Aguardando QR Code, Conectando, Desconectado), foto e nome do perfil pareado, quantidade de mensagens enviadas hoje e no mês, taxa de entrega e quantidade de falhas. Também permite enviar uma mensagem de teste para validar a integração sem precisar fazer uma reserva real, e desconectar o número quando você trocar de aparelho ou de chip. O usuário normalmente chega aqui logo após a primeira ativacao do módulo whatsapp-mensagens ou quando recebe um alerta de que o WhatsApp caiu.

A integração padrão usa Evolution GO API (servidor proprio do Viagilize em Docker porta 8086, com instancia individual por empresa). empresas que precisam da API Oficial Meta WhatsApp Business usam um fluxo separado - ha um link no proprio card de conexao para configurar tokens, phone_number_id e WABA.

Como usar

Conectar pela primeira vez

1. Va em Modulos > WhatsApp Mensagens no sidebar (URL /admin/whatsapp).
2. Confirme que o badge no topo da página esta Desconectado (bolinha vermelha).
3. No card Conexao WhatsApp, clique no botao verde Conectar WhatsApp. O sistema vai provisionar automaticamente uma instancia no Evolution GO (caso ainda não exista) e gerar o QR Code.
4. Abra o WhatsApp no celular que será vinculado:
   • Android: toque nos tres pontos no canto superior direito > Aparelhos conectados > Conectar um aparelho.
   • iPhone: va em Ajustes (engrenagem) > Aparelhos conectados > Conectar um aparelho.
5. Aponte a camera para o QR Code exibido na tela. O contador na página mostra quantos segundos restam ate o código expirar (limite de 90 segundos).
6. Aguarde a página atualizar sozinha. O status muda para Conectado, surge a foto de perfil, o nome e o número pareado, e um alerta de sucesso aparece pedindo para recarregar a página.

Enviar mensagem de teste

1. Com o status Conectado, va ao segundo card Enviar Mensagem de Teste (lado direito da página).
2. No campo Número do WhatsApp, digite um celular com DDD (formato (99) 99999-9999). O campo ja vem pre-preenchido com o WhatsApp cadastrado na empresa, se houver.
3. Clique em Enviar Teste. O sistema envia uma mensagem informando que a integração esta funcionando.
4. Confira o resultado no banner verde/vermelho que aparece abaixo do botao e no celular que recebeu a mensagem.

Desconectar

1. Com o status Conectado, role ate o card Conexao WhatsApp.
2. Clique no botao Desconectar (em vermelho, abaixo dos dados do perfil pareado).
3. Confirme no modal. A instancia e encerrada e o status volta para Desconectado. As automacoes de envio param ate o número ser reconectado.

Casos especiais

QR Code expirou antes de escanear

Cada QR Code dura 90 segundos. Se não for lido a tempo, a imagem some e aparece o aviso QR Code Expirado com o botao Gerar Novo QR Code. Clique nele para pedir um código novo ao Evolution. Não e preciso recarregar a página inteira.

Cancelar a tela do QR Code

Enquanto o QR Code esta visivel, ha um link discreto Cancelar logo abaixo. Ao clicar, o sistema chama o endpoint de disconnect no servidor (para parar a instancia de gerar novos QRs) e volta o status local para Desconectado.

empresa ja usa o Chatbot WhatsApp na mesma instancia

Se o módulo Chatbot WhatsApp estiver ativo e configurado para instancia compartilhada, aparece um aviso roxo logo abaixo dos cards de estatisticas: "O Chatbot WhatsApp esta usando esta mesma instancia para enviar e receber mensagens. Se desconectar aqui, o chatbot também será afetado." O link Gerenciar conexao do chatbot leva para a tela equivalente do chatbot. Desconectar aqui derruba ambos.

Provider e API Oficial do Meta

O badge no canto direito do card Conexao WhatsApp identifica qual provider esta em uso:

• Evolution GO API (laranja): integração não oficial. Mais flexivel (qualquer número pessoal funciona), mas o WhatsApp pode banir o número se ele for usado para envios em massa.
• API Oficial Meta (verde): integração oficial via Meta Cloud API. Sem risco de banimento, porem exige conta Business verificada e templates aprovados pela Meta para enviar mensagens fora da janela de 24h. Para migrar, clique em configure aqui no banner amarelo (rota /admin/whatsapp/meta). Quando o provider e Meta, o teste usa o template hello_world (pre-aprovado em qualquer WABA).

Provisionamento automático da instancia

Na primeira tentativa de conectar, se você ainda não tem token no Evolution GO, o sistema cria a instancia automaticamente antes de pedir o QR. Antes esse passo era manual via SSH; hoje basta clicar em Conectar WhatsApp. Se a criação falhar com erro diferente de "ja existe", o suporte precisa ser acionado (mensagem Falha ao criar instancia no servidor).

Erros comuns e como resolver

• "Não foi possível gerar o QR Code. Tente novamente." - Causa: instabilidade no servidor Evolution GO (Docker porta 8086) ou a instancia esta em estado intermediario. Solucao: clique em Gerar Novo QR Code após alguns segundos; se persistir, contate o suporte.
• "Falha ao criar instancia no servidor. Contate o suporte." - Causa: o auto-provisionamento da instancia no Evolution GO falhou (problema no token central ou no servidor). Solucao: o suporte precisa criar a instancia manualmente no painel Evolution.
• "Instancia ja existe mas sem token. Contate o suporte para regenerar." - Causa: instancia foi criada anteriormente mas o token não foi gravado na WhatsAppConfig. Solucao: superadmin precisa regerar o token via painel do Evolution e gravar na sua empresa.
• "WhatsApp não esta conectado." (ao tentar enviar teste) - Causa: tentou disparar o teste antes de o status virar Conectado. Solucao: faca o pareamento via QR Code primeiro e so depois envie o teste.
• "Erro ao enviar mensagem: ..." - Causa: o número de destino e invalido, esta fora da janela de 24h (Meta) ou a instancia caiu. Solucao: verifique se o número esta no formato correto com DDD; no provider Meta, confirme que o template hello_world esta liberado na WABA.
• QR Code sumiu sem mensagem de erro - Causa: passou dos 90 segundos do timeout local. Solucao: clique em Gerar Novo QR Code para pedir outro.

Onde encontrar

• URL: /admin/whatsapp
• Caminho no menu: Modulos > WhatsApp Mensagens
• Permissão necessária: ver o WhatsApp
• Módulo necessário: whatsapp-mensagens (alem do uma trava de acesso que valida aceite dos termos de uso)

Veja também

• WhatsApp Automático - visao geral do modulo
• Configurações do WhatsApp
• Templates de mensagens
• Histórico de mensagens enviadas