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.20261004011426do SDK, que inclui os métodos tipadosanalytics.geteanalytics.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.
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. AdicioneprojectId para
ler um projeto, ou sessionId para ler um Número:
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:
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édiasnull. 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.