Pular para o conteúdo principal
Use Client.analytics para ler a atividade agregada do WhatsApp de uma equipe, um projeto ou um Número. O recurso inclui engajamento das mensagens, tempos de resposta, problemas de conexão e resultados de chamadas registrados.

Antes de começar

  • Instale a versão 0.1.0-dev.20261004011426 do SDK, que inclui os métodos tipados analytics.get e analytics.metrics.
  • Use uma credencial de servidor com sessions:read. Tokens de cliente do navegador não podem ler as análises da Platform.
  • Peça a um proprietário ou administrador da equipe para ativar Análises no Console. A coleta começa depois da ativação; a atividade de mensagens anterior não é reconstruída.
Os métodos exigem um ambiente da API que exponha as Análises. Instalar o SDK não ativa a coleta nem concede acesso. Veja a instalação para os requisitos de runtime e crie um cliente para as credenciais.

Leia as últimas 24 horas

start e end são milissegundos Unix. Omita-os para obter os 30 dias anteriores. O intervalo máximo é de 366 dias. Recalcule os timestamps a cada leitura para ter uma janela móvel. numbers contém medições por Número; series contém intervalos de mensagens e de atividade; callSeries contém resultados diários de chamadas, em UTC, por Número.

Filtre um projeto ou Número

Uma credencial da organização lê a própria equipe. Adicione projectId para ler um projeto, ou sessionId para ler um Número:
Os dois identificadores são UUIDs de registro. sessionId é o ID de registro do Número, não o número de telefone nem o nome de exibição. Para uma credencial de projeto, vincule o cliente a esse projeto:
Um cliente vinculado a um projeto usa a rota do projeto e rejeita um projectId diferente. A API também aplica o escopo da credencial. UUIDs e intervalos de datas inválidos lançam PolymorfaValidationError antes de uma solicitação. Trate falhas de autenticação, de permissão e do serviço com erros e novas tentativas.

Mantenha a cobertura junto com a medição

As taxas de leitura e de resposta usam conversas diretas de 24 horas já concluídas. Uma taxa de leitura conta confirmações de leitura do WhatsApp observadas, não aberturas do app. A falta de confirmações não prova que uma mensagem não foi lida. Preserve taxas e médias null. Um denominador ausente ou uma cobertura incompleta não significa engajamento zero. Verifique measured, engagement.complete e messageAnalysis.complete junto com os valores. Verifique responseQueue.complete e responseQueue.observedAt antes de apresentar o retrato das respostas em espera. messageAnalysis.segments compara o tipo de mensagem, a faixa de tamanho do texto e a origem do envio. Use conversationBreakdown.rows para cruzar essas categorias com o país do destinatário e as faixas de quantidade de dispositivos vinculados. Campos de país ou de quantidade ausentes em linhas mais antigas continuam como Desconhecido. A contagem de dispositivos vinculados exclui o dispositivo principal. Essas proporções contam conversas, não pessoas únicas, e não estabelecem causas de conversão. accountActivity inclui os períodos concluídos de atividade do telefone e os intervalos de silêncio, as somas das durações, as contagens de amostras e médias que podem ser nulas. As linhas das séries incluem somas e contagens para comparações ponderadas. Esses sinais não medem se o telefone está ligado nem um tempo online/offline verificado. calls inclui os resultados de chamadas recebidas e feitas, os tempos de atendimento e de conversa observados, medições de qualidade que podem ser nulas e as janelas de retorno de chamadas perdidas. Os registros de chamadas têm a própria política de retenção. Veja as definições das medições antes de interpretar esses campos.

Exporte métricas

analytics.metrics retorna o texto das métricas em data e os detalhes HTTP em metadata:
windowHours é um inteiro de 1 a 168, com 24 como padrão. A janela abrange horas UTC completas. segments tem false como padrão; format tem "prometheus" como padrão. Os clientes de equipe e de projeto aceitam o método e o mesmo filtro de Número. Essas métricas são gauges por janela. Não aplique rate() nem increase(). Com as Análises desativadas, a resposta traz a ativação e os metadados da janela, sem métricas de negócio. Para coletar continuamente, use o guia de configuração do OpenTelemetry e do Prometheus. Para receber retratos JSON ou NDJSON a cada hora no seu endpoint, crie um destino em Configurações do projeto → Destinos; veja destinos de análises.

Atividade dos destinatários

summary.recipientActivity e o recipientActivity de cada número expõem observações opcionais de destinatários por hora. Use recipientCountry, recipientDeviceCount e deviceSource para selecionar as linhas a agregar. Os metadados das mensagens são coletados em conjunto em conversationBreakdown; não deduza cruzamentos por tipo de mensagem a partir de totais independentes de atividade dos destinatários. Entrega, leitura, mensagens recebidas e presença continuam sendo quantidades separadas. Verifique a cobertura antes de calcular taxas ou médias de tempo. Veja atividade dos dispositivos e as definições de horário comercial.