> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leia as análises do WhatsApp

> Leia o engajamento das mensagens, as operações de resposta, os resultados de chamadas e os intervalos de atividade, e depois exporte métricas para o seu coletor.

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.

```bash theme={null}
npm install --save-exact @polymorfa/sdk@0.1.0-dev.20261004011426
```

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](/pt-br/sdks/typescript/installation) para os requisitos de runtime
e [crie um cliente](/pt-br/sdks/typescript/client) para as credenciais.

## Leia as últimas 24 horas

```typescript theme={null}
import { Client } from "@polymorfa/sdk";

const platform = new Client({
  credential: {
    type: "organizationApiKey",
    value: process.env.POLYMORFA_KEY!,
  },
  apiVersion: "2026-09-22",
});

const end = Date.now();
const { data } = await platform.analytics.get({
  start: end - 24 * 60 * 60 * 1_000,
  end,
});

if (!data.enabled) {
  console.log("Analytics is off");
} else {
  console.log(data.summary?.outgoingMessages);
  console.log(data.summary?.engagement.readRate);
  console.log(data.summary?.engagement.replyRate);
  console.log(data.summary?.averageBusinessResponseMs);
  console.log(data.summary?.calls.directions.inbound.missed);
}
```

`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:

```typescript theme={null}
const result = await platform.analytics.get({
  projectId: "22222222-2222-4222-8222-222222222222",
  sessionId: "33333333-3333-4333-8333-333333333333",
  start: end - 24 * 60 * 60 * 1_000,
  end,
});

console.log(result.data.numbers);
```

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:

```typescript theme={null}
const project = new Client({
  credential: { type: "projectToken", value: process.env.POLYMORFA_PROJECT_KEY! },
  projectId: "22222222-2222-4222-8222-222222222222",
  apiVersion: "2026-09-22",
});

const projectAnalytics = await project.analytics.get({ start: end - 86_400_000, end });
console.log(projectAnalytics.data.summary);
```

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](/pt-br/sdks/typescript/errors).

## 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](/pt-br/console/analytics) antes de interpretar esses
campos.

## Exporte métricas

`analytics.metrics` retorna o texto das métricas em `data` e os detalhes HTTP em
`metadata`:

```typescript theme={null}
const metrics = await platform.analytics.metrics({
  projectId: "22222222-2222-4222-8222-222222222222",
  windowHours: 24,
  segments: true,
  format: "openmetrics",
});

console.log(metrics.data);
console.log(metrics.metadata.status);
```

`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](/pt-br/console/analytics-collectors).
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](/pt-br/console/analytics-collectors#enviar-retratos-json-por-hora).

## 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](/pt-br/sdks/typescript/devices#leia-a-atividade-dos-dispositivos-dos-destinatários)
e as [definições de horário comercial](/pt-br/console/analytics#atividade-dos-destinatários-e-horário-comercial).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.