WhatsApp - Dashboard de Metricas

O que é

O dashboard de metricas do WhatsApp consolida os numeros do envio da sua empresa para uma leitura executiva: quantas mensagens foram disparadas hoje e no mês, qual a taxa de entrega, quantas falharam e como o volume se distribui por status, categoria e tipo. Ele complementa a listagem detalhada do Histórico de Mensagens, que mostra cada envio individualmente.

O usuário normalmente chega aqui depois de conectar o WhatsApp e ativar as automacoes, ou quando precisa investigar uma queda de entregabilidade (clientes reclamando que não receberam confirmação, lembrete ou cobranca). Os KPIs aparecem em dois lugares: na página principal do modulo (/admin/whatsapp), com os quatro cards do mês, e na propria página de Histórico (/admin/whatsapp/messages), com tres cards que refletem o período filtrado pelo usuário.

Como usar

1. Va em WhatsApp no sidebar para abrir o dashboard principal em /admin/whatsapp.
2. Leia o bloco superior de quatro cards:
   • Hoje (icone azul) - mensagens enviadas hoje.
   • Este Mês (icone verde-esmeralda) - total de mensagens do mês corrente.
   • Taxa de Entrega (icone verde) - percentual de mensagens do mês que sairam com status sent, delivered ou read. O subtitulo mostra quantas foram efetivamente entregues.
   • Falhas (icone vermelho) - quantas mensagens do mês terminaram em failed.
3. Para entrar na visao por mensagem, abra Histórico de Mensagens em /admin/whatsapp/messages. Acima da tabela ficam tres cards:
   • Total - quantas mensagens batem os filtros aplicados.
   • Enviadas - soma de sent, delivered e read no recorte.
   • Falhas - quantas falharam no recorte.
4. Aplique filtros (telefone, status, tipo, categoria, data início, data fim) para recortar o período desejado. Os tres cards de cima recalculam automaticamente para o recorte. Use o link Limpar (botao vermelho a direita dos filtros) para voltar ao default.
5. Para puxar dados brutos para um grafico ou planilha, chame o endpoint JSON GET /admin/whatsapp/dashboard-data?days={dias} (default 30). Ele retorna quatro blocos:
   • daily - mensagens por dia no período.
   • byStatus - total agrupado por status (pending, sent, delivered, read, failed).
   • byCategory - total por categoria (reserva, pagamento, lembrete, cliente, sistema).
   • byType - total por tipo (notification, reminder, verification, manual).

Casos especiais

Taxa de Entrega em 0% com mensagens enviadas

O calculo da taxa do mês usa a base mensagens do mês, não mensagens enviadas. Se nenhuma mensagem chegou a sair (todas em pending ou failed), a taxa fica em 0%. Verifique antes a conexao em WhatsApp > Conexao e o limite por hora em WhatsApp > Configurações.

Card de Falhas alto mas listagem aparece vazia

A página /admin/whatsapp/messages traz por padrão todas as datas. Se o filtro Data início ou Data fim estiver preenchido, os cards refletem apenas o recorte. Limpe os filtros (botao Limpar) para validar o total geral.

Chatbot compartilhando a mesma instancia

Quando o módulo Chatbot WhatsApp esta ativo com instance_source = compartilhada, aparece um banner indigo abaixo dos cards avisando que desconectar o WhatsApp aqui também afeta o chatbot. Isso muda como os numeros de falha precisam ser interpretados: pode ser efeito colateral de uma desconexao do chatbot.

Provider Meta Cloud vs Evolution GO

Os KPIs são agnosticos ao provider - somam tudo que esta gravado na tabela whatsapp_messages da sua empresa. O badge Evolution GO API ou API Oficial Meta no card de Conexao indica qual provider esta gerando esses numeros no momento.

Erros comuns e como resolver

• "Taxa de Entrega em 0%" - Causa: nenhuma mensagem do mês saiu com sent/delivered/read ou todas estao pending/failed. Solucao: cheque a conexao em WhatsApp > Conexao, leia o card de Falhas e abra a listagem filtrando por Status = Falha para ver o error_message.
• "Falhas subiu de repente" - Causa: comum em troca de provider (Evolution GO para Meta) sem migrar os templates aprovados, em desconexao da Evolution GO, ou em limites de envio atingidos. Solucao: confira o badge do provider em /admin/whatsapp, verifique o status da conexao e revise Configurações > Limite por hora.
• "Número invalido" (badge laranja na listagem) - Causa: o meio de pagamento retornou que o telefone não possui WhatsApp. Solucao: corrija o cadastro do cliente e reenvie pelo botao Reenviar na linha da mensagem.
• "Dashboard não bate com o relatório do cliente" - Causa: KPIs do dashboard contam mensagens disparadas pelo sistema, não conversas humanas. O Viagilize não registra mensagens enviadas direto do celular/WhatsApp pessoal. Solucao: explique ao usuário que a base e somente o envio automático/manual feito pela plataforma.

Onde encontrar

• URL: /admin/whatsapp/messages (KPIs no topo da listagem)
• URL alternativa: /admin/whatsapp (cards principais do mês)
• Endpoint JSON: GET /admin/whatsapp/dashboard-data?days={dias}
• Caminho no menu: WhatsApp > Histórico de Mensagens (ou página inicial do modulo)
• Permissão necessária: ver o WhatsApp
• Módulo necessário: WhatsApp Mensagens (whatsapp-mensagens)

Veja também

• Histórico de Mensagens (listagem detalhada)
• Conectar seu WhatsApp
• Configurações WhatsApp
• Templates de WhatsApp