Métricas do WhatsApp
A página Metrics no dashboard do Bird mostra como está o seu canal WhatsApp: quanto chegou ao dispositivo do destinatário, se a sua taxa de falha está variando e quão rápido tudo se moveu. Este guia percorre essa página, o que cada número significa e quando agir.
Métricas são a visão agregada de tudo que o seu espaço de trabalho envia. Para o ciclo de vida de uma mensagem individual (este número recebeu a mensagem, e quando), veja o log do WhatsApp e os eventos.
Leia suas métricas
A página Metrics fica em WhatsApp → Metrics no dashboard do Bird; ela é visível para membros do espaço de trabalho que possuam as permissões de leitura de WhatsApp e de leitura de Analytics. Todos os números respeitam o seletor de período (últimas 24 horas, 7, 30 ou 90 dias). Novos eventos aparecem após agregação e replicação, então o período mais recente é provisório.
As taxas de saída usam o horário de aceitação de cada mensagem. Um recibo de entrega que chega hoje para uma mensagem aceita ontem conta para ontem, junto com o accepted dessa mensagem. Cada período, portanto, acompanha as mensagens aceitas nele à medida que as observações chegam. As horas mais recentes podem sub-reportar delivered enquanto os recibos ainda estão chegando. accepted é o denominador dos cards de taxa de entrega e taxa de falha.
As contagens representam mensagens distintas para cada evento observado e podem ser aproximadas em escala. Elas não são um funil obrigatório: um recibo de leitura pode existir sem um recibo de entrega, e observações ausentes podem deixar lacunas entre estágios. Estatísticas de grupo também contam mensagens, não destinatários; a primeira entrega observada de um participante pode incrementar a contagem de entregues antes que todos os membros do grupo tenham recebido a mensagem.
Os cards resumo
A fileira de cards no topo é a sua verificação rápida de saúde:
- Taxa de entrega: mensagens entregues como proporção das aceitas. O card exibe Healthy acima de 95%. Nesse valor ou abaixo dele, algo está falhando em chegar aos dispositivos: números inválidos, uma janela de atendimento expirada ou um problema de template. O histograma de causas de falha (veja Taxa de falha e suas causas) indica qual.
- Taxa de falha: a proporção de mensagens aceitas que terminaram failed. O card mostra sua taxa contra um limite de 5% com uma barra de progresso; ao atingi-lo, o card muda para Risk. Uma taxa de falha alta e sustentada geralmente aponta para qualidade da lista, uma janela de atendimento ao cliente expirada ou um limite de taxa da Meta.
- Aceitas: a contagem bruta de mensagens aceitas no período, com o número encaminhado para a rede WhatsApp (sent).
Os limites de 95% e 5% são os indicadores que usamos para colorir os cards. Eles são deliberadamente conservadores; um card pode exibir Healthy e ainda ter espaço para melhorar.
Entregas ao longo do tempo
O gráfico de entregas plota o volume de mensagens aceitas, entregues e com falha ao longo do período para que você identifique tendências e picos isolados: uma campanha ruim, uma importação de lista de números que deu errado, um template que começou a ser rejeitado. O tamanho do intervalo acompanha o período (por hora para 24 horas, por dia para janelas mais longas).
Taxa de falha e suas causas
Abaixo do gráfico de entregas na página Metrics, uma linha de taxa de falha plota a taxa por intervalo ao longo do período, enquanto o card resumo de taxa de falha mantém o valor da janela inteira. Um histograma detalha as falhas por código de erro normalizado, classificado por contagem com a proporção de cada código nas mensagens com falha. As razões de falha do WhatsApp são um conjunto aberto, então o histograma lista os códigos que realmente ocorreram no período em vez de uma lista fixa; uma barra crescente em um código aponta direto para a correção.
Latência de entrega
A tabela de latência reporta dois estágios nos percentis p50, p95 e p99:
- Processamento: da aceitação da mensagem até o envio bem-sucedido ao provedor WhatsApp. Um percentil lento aqui pede investigação do caminho de envio, incluindo o envio ao provedor.
- Total: de ponta a ponta, da aceitação da mensagem até o WhatsApp confirmar a entrega ao dispositivo do destinatário. A diferença entre Total e Processamento é a rede WhatsApp e o dispositivo do destinatário, que não controlamos. Um telefone offline por uma hora aumenta o Total sem alterar o Processamento.
Use p95/p99 para capturar a cauda lenta: uma mediana saudável com um p99 lento geralmente aponta para um template ou destino atrasado. A latência é um valor da janela inteira; um estágio ou percentil sem dados para o período exibe um placeholder.
Detalhamentos
O painel Breakdowns fatia os mesmos números de entrega para que você isole um problema até a sua origem:
- Por número: o volume de aceitas, entregues e com falha de cada número de negócio remetente com sua taxa de entrega, para que você compare remetentes lado a lado.
- Por template: o mesmo recorte por template, para encontrar o template que está puxando uma taxa para baixo.
- Por categoria de template: o mesmo recorte pelas categorias de template da Meta, o corte que também determina o seu gasto.
- Por tag: as tags que você anexa a um envio, o corte mais flexível: marque uma campanha, template ou variante de experimento e compare-os diretamente.
- Por país: o mesmo recorte por país de destino, para ver se um problema de entrega acompanha um mercado em vez de um remetente ou template. Um destinatário cujo país não pode ser determinado (um número que parece um número de telefone mas não pertence a nenhum país, ou uma faixa internacional como freephone) é contado sob ZZ, o mesmo placeholder que o detalhamento por país do SMS usa. Envios em grupo são excluídos porque um grupo pode abranger vários países e não tem um único destino. A cobertura histórica de países anterior ao lançamento deste detalhamento pode estar incompleta, incluindo observações de entrega ou leitura sem contagens de aceitas correspondentes. O histórico agregado sobrevive à janela de 30 dias de detalhes de mensagem; esperar 30 dias não corrige essas coortes mais antigas.
Cada linha também recebe um status derivado (Healthy, Watching ou Throttled) baseado nas suas próprias taxas de entrega e falha, para que um número ou categoria com problemas se destaque sem você precisar ler cada coluna. Cada aba classifica as primeiras linhas do período; quando uma dimensão tem mais valores distintos do que cabem, o painel indica "Top N of M".
Acesso programático
Os agregados por trás desta página também são uma API pública. Métodos tipados estão disponíveis nos SDKs de TypeScript, Python, PHP e Go sob bird.whatsapp.stats, a bird CLI os expõe como bird whatsapp stats <verb>, e um agente os acessa pelas whatsapp_stats_* MCP tools. Os esquemas completos de solicitação e resposta estão na referência do API.
O agregado e a série temporal
GET /v1/whatsapp/stats/summary retorna uma linha agregada para a janela: contagens de ciclo de vida (accepted, sent, delivered, failed, rejected) com taxas de entrega e falha, engajamento (read, read_rate) e percentis de latência (p50, p95, p99) para três estágios: processamento, entrega e total. /daily e /hourly retornam as mesmas contagens de ciclo de vida e leitura em uma linha por dia ou hora do calendário, cada uma com seus próprios percentis de latência; apenas as taxas (delivery_rate, failure_rate, read_rate) são valores da janela inteira, leia-as a partir de /summary. Os três aceitam um filtro de dimensão por vez: template, category, tag ou phone_number. Aqui, phone_number restringe a um único remetente de negócio, no formato E.164, não o contato pelo qual filtra no parâmetro deprecado phone_number de GET /v1/whatsapp/messages.
A taxa de leitura é read / delivered, enquanto as taxas de entrega e falha usam accepted. Um denominador zero retorna null, indicando que a taxa não pode ser calculada. A taxa de leitura não é limitada a 100%, então observações de entrega ausentes podem produzir um valor mais alto; isso é uma lacuna de observação a investigar, não evidência de que mais do que todos os destinatários leram a mensagem.
Os percentis de latência usam amostras registradas. Uma amostra de latência de entrega ausente não implica latência zero, e a latência total pode estar presente quando o timestamp intermediário de envio não estava disponível. Não calcule a média de percentis finalizados de intervalos separados. Eventos reenviados podem afetar distribuições de latência mesmo quando as contagens de mensagens distintas permanecem deduplicadas.
Quando presente, data_as_of reporta a atualidade da agregação. Ele não prova que todos os callbacks do provedor chegaram ou que a cobrança foi liquidada. Um valor de atualidade null significa que ele não estava disponível para aquela resposta.
Escolhendo a janela
from e to aceitam um dia do calendário ou um instante RFC 3339, mas quais formas cada endpoint aceita difere:
| Endpoint | Limites | Janela máxima |
|---|---|---|
| /summary | Ambos dias do calendário, ou ambos instantes RFC 3339 | 365 dias, ou 720 horas com instantes |
| /daily | Apenas dias do calendário | 365 dias |
| /hourly | Apenas instantes RFC 3339 | 720 horas (30 dias) |
No /summary, misturar um limite de dia com um limite de instante retorna 422. Limites de instante são arredondados para baixo até a hora em /summary e /hourly, os únicos dois que os aceitam. Defina timezone com um identificador IANA para calcular limites de dia e hora localmente em vez de em UTC; uma vez definido, um offset numérico UTC como +05:45 em um limite de instante é rejeitado. Adicione compare=previous_period a /summary para obter a janela anterior de tamanho igual e a variação em relação a ela.
Detalhamentos
Seis endpoints classificam os mesmos números de entrega por uma dimensão, cada um já de dimensão única, então nenhum aceita filtro: por número, por template, por categoria de template, por tag e por código de erro (apenas mensagens com falha, agrupadas por razão de falha normalizada). As linhas são classificadas por volume aceito (contagem de falhas para códigos de erro) e limitadas a limit (padrão 50, máximo 200). Um envio sem valor para uma dimensão está ausente desse detalhamento: um envio de forma livre não resolve nenhum template, e um envio sem tag nenhuma tag. Uma mensagem com várias tags pode aparecer em várias linhas de tag, então somar essas linhas não fornece o volume único do espaço de trabalho. Compare um detalhamento consigo mesmo ao longo do tempo. Todas as linhas, exceto as de código de erro, também trazem seus próprios percentis de latency. Um sexto, por país, agrupa os mesmos números pelo mercado de destino do destinatário; um destinatário cujo país não pode ser resolvido conta sob ZZ, e envios em grupo estão ausentes porque um envio pode abranger vários países.
Mensagens recebidas
Quatro endpoints sob /v1/whatsapp/stats/inbound/ cobrem o que os seus números receberam em vez de enviaram: resumo, diário, por hora e por número de telefone. Cada linha traz apenas uma contagem de received e segue o horário de ocorrência da mensagem recebida. Uma mensagem recebida não tem ciclo de vida de entrega de saída para detalhar. Eles estão aninhados sob bird.whatsapp.stats.inbound nos SDKs e bird whatsapp stats inbound <verb> na CLI.
Reconciliação por mensagem
Os endpoints de estatísticas respondem perguntas agregadas; eles não substituem consultas por mensagem. Para confirmar o que aconteceu com uma mensagem, consuma eventos de webhook conforme eles ocorrem, ou percorra GET /v1/whatsapp/messages e o endpoint de eventos de cada mensagem, cujos filtros (status, destinatário, tag, janela de tempo) cobrem a maioria dos trabalhos de reconciliação.
Próximos passos
- Analytics do WhatsApp: conecte observações de mensagens a resultados confirmados de clientes
- Log do WhatsApp: a visão por mensagem por trás dos números agregados
- Eventos: o fluxo de ciclo de vida por mensagem do qual as métricas são derivadas
- Enviando mensagens WhatsApp: categorias, tags e o modelo de custo por mensagem
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação