Análise do WhatsApp

As análises do WhatsApp permitem que você obtenha métricas detalhadas sobre números de telefone comerciais e modelos associados à sua conta WABA. Entre os exemplos estão o número e o tipo de mensagens enviadas, o número de vezes que um determinado modelo foi lido e o número de vezes que um botão em um modelo foi clicado.

Análise de mensagens

A análise de mensagens fornece o número e o tipo de mensagens enviadas e entregues pelos números de telefone associados a um WABA específico.

Exemplo de solicitação

Para obter análises de mensagens, envie uma solicitação GET para o seguinte endpoint, substituindo waba_id com o ID do Account do WhatsApp Business para o qual você deseja obter os dados analíticos de mensagens:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/messaging-analytics

Os dados são retornados com granularidade de meia hora, diária ou mensal no fuso horário UTC, com um período de análise retroativa de até 90 dias. É necessário incluir os parâmetros de início, fim e granularidade na sua solicitação; além disso, há alguns parâmetros opcionais que você pode usar para filtrar ainda mais os dados:

Nome Tipo Obrigatório Notas
start string(timestamp) Sim O formato da data e hora de início para os dados analíticos a serem recuperados, no formato YYYY-MM-DD.
end string(timestamp) Sim O formato da data e hora de término para os dados analíticos a serem recuperados, no formato YYYY-MM-DD.
granularity sequência de caracteres Sim A granularidade dos dados analíticos a serem recuperados. Valores aceitos: HALF_HOUR, DAILY, MONTHLY
phone_number matriz Não Números de telefone dos quais você deseja obter dados analíticos. Se o campo estiver vazio, todos os números de telefone associados ao WABA serão incluídos.
product_types matriz Não Uma matriz com os tipos de mensagem para os quais se deseja recuperar análises. Os valores possíveis são: 0 para mensagens de notificação e/ou 2 para mensagens de suporte ao cliente. Caso não seja especificado, serão exibidas as métricas de todos os tipos de mensagem.
country_codes matriz Não Códigos de país de duas letras para os países dos quais você deseja obter dados analíticos. Se não forem especificados, serão exibidos os dados analíticos de todos os países.

Você pode encontrar um exemplo completo de código no Recuperar análises de mensagens trecho de código.

Exemplo de resposta

{
   "id": "345688589250625",
   "granularity": "HALF_HOUR",
   "phone_numbers": [
      "16505550111"
   ],
   "country_codes": [
      "US"
   ],
   "_embedded": {
      "messaging_analytics": [
         {
            "start": "1543543200",
            "end": "1543629600",
            "sent": 100,
            "delivered": 90
         }
      ]
   },
   "paging": {
      "cursors": {
         "before": "MAZDZD",
         "after": "MjQZD"
      },
      "next": "https://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?after=MAZDZD",
      "previous": "https://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?before=MjQZD"
   }
}

Análise de modelos

As métricas de modelos descrevem o número de vezes que um modelo foi enviado, entregue e lido, bem como o número de vezes que os botões de URL ou de resposta rápida no modelo foram clicados; as métricas de cliques em botões estão disponíveis apenas para modelos classificados como MARKETING ou UTILITY.

Os dados são fornecidos com granularidade diária no fuso horário UTC, com um período de análise retrospectiva de até 90 dias.

Observação: é necessário confirmar as métricas de modelos no seu account empresarial antes de poder acessá-las. Consulte o Documentação do WhatsApp para mais informações.

Exemplo de carga útil de solicitação

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/794579786527563/template-analytics?template_ids=['1441569584015671','2266692337158554']&start=2026-01-11&end=2026-01-21&metric_types=['DELIVERED']

Exemplo de resposta

{
    "page_size": 100,
    "_embedded": {
        "template_analytics": [
            {
                "template_id": "1441569584015671",
                "start": "2026-01-11T00:00:00Z",
                "end": "2026-01-12T00:00:00Z",
                "delivered": 0
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-12T00:00:00Z",
                "end": "2026-01-13T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-13T00:00:00Z",
                "end": "2026-01-14T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-14T00:00:00Z",
                "end": "2026-01-15T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-15T00:00:00Z",
                "end": "2026-01-16T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-16T00:00:00Z",
                "end": "2026-01-17T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-17T00:00:00Z",
                "end": "2026-01-18T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-18T00:00:00Z",
                "end": "2026-01-19T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-19T00:00:00Z",
                "end": "2026-01-20T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "1441569584015671",
                "start": "2026-01-20T00:00:00Z",
                "end": "2026-01-21T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-11T00:00:00Z",
                "end": "2026-01-12T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-12T00:00:00Z",
                "end": "2026-01-13T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-13T00:00:00Z",
                "end": "2026-01-14T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-14T00:00:00Z",
                "end": "2026-01-15T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-15T00:00:00Z",
                "end": "2026-01-16T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-16T00:00:00Z",
                "end": "2026-01-17T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-17T00:00:00Z",
                "end": "2026-01-18T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-18T00:00:00Z",
                "end": "2026-01-19T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-19T00:00:00Z",
                "end": "2026-01-20T00:00:00Z",
                "delivered": "0"
            },
            {
                "template_id": "2266692337158554",
                "start": "2026-01-20T00:00:00Z",
                "end": "2026-01-21T00:00:00Z",
                "delivered": "0"
            }
        ]
    },
    "granularity": "DAILY",
    "product_type": "cloud_api",
    "_links": {
        "self": {
            "href": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/794579786527563/template-analytics?template_ids=[1441569584015671,2266692337158554]&start=2026-01-11&end=2026-01-21&metric_types=[DELIVERED]&page_size=100&cursor=c2VsZj1udWxs"
        }
    }
}

Ativação da análise de modelos

Antes de poder acessar as análises de modelos da sua conta do WhatsApp Business (WABA), é necessário habilitar a coleta de insights no nível da WABA. Insights são dados analíticos relacionados a mensagens, preços ou modelos, incluindo o rastreamento de cliques em botões ou links dos modelos. Essa é uma etapa de configuração única, realizada para cada WABA.

Importante: Ao ativar os insights, a Meta passa a coletar e tornar anônimos os dados de suas conversas com os clientes. A Meta utiliza esses dados anônimos para melhorar os serviços do WhatsApp. Uma vez ativada, a análise de modelos não pode ser desativada para toda a WABA. A ativação é feita uma vez por ID da WABA (não por modelo ou número de telefone).

A ativação dos insights permite que a Meta:

  • Colete dados anônimos de bate-papo do seu WABA
  • Gerar análises de modelos que mostrem métricas de entrega, leitura e cliques
  • Forneça esses dados por meio da API do Template Analytics

Ative o Insights para o seu WABA

Ponto final: PATCH /v1/channel-manager/whatsapp/wabas/{waba_id}/enable_insights

Utilize o mesmo método de autenticação que os outros pontos de conexão do Channel Manager. A chave de API deve estar vinculada ao WABA ID.

Códigos de resposta:

Código Descrição
200 Solicitação bem-sucedida — o recurso “Insights” foi ativado com sucesso
403 Não autorizado — a chave da API não está vinculada a este ID WABA
404 Recurso não encontrado — O ID da WABA é inválido

Depois que os insights forem ativados, aguarde alguns minutos para que a configuração seja aplicada. Em seguida, você poderá começar a recuperar os dados analíticos dos modelos.

Exemplo de solicitação

Para obter as métricas do modelo, envie uma solicitação GET para o seguinte endpoint, substituindo waba_id com o ID da conta do WhatsApp Business para a qual você deseja obter os dados analíticos dos modelos:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/template-analytics

Os parâmetros de consulta detalhados a seguir podem ser usados para filtrar os resultados:

Nome Tipo Obrigatório Notas
start string(timestamp) Sim O formato da data e hora de início para os dados analíticos a serem recuperados, no formato YYYY-MM-DD.
end string(timestamp) Sim A data e a hora finais até as quais os dados analíticos devem ser recuperados, no formato YYYY-MM-DD. A diferença máxima entre as datas de início e de término é de 90 dias.
granularity sequência de caracteres Sim Deve ser DIÁRIO.
template_ids matriz Sim Uma matriz do template_ids dos modelos para os quais deseja obter dados analíticos. Máximo de 10.
metric_types matriz Não Uma matriz com os tipos de métricas para as quais se deseja recuperar análises. Os valores possíveis são: SENT, DELIVERED, READ, e CLICKED. Você pode ler mais sobre o que cada tipo significa na documentação do WhatsApp. Se estiver vazio, serão retornadas as análises para todos os tipos de métricas.

Exemplo de resposta

{
   "granularity": "DAILY",
   "product_type": "cloud_api",
   "page_size": 100,
   "_embedded": {
      "template_analytics": [
         {
            "template_id": "458951126288942",
            "start": "2024-11-11T00:00:00Z",
            "end": "2024-11-11T00:00:00Z",
            "sent": 100,
            "delivered": 90,
            "read": 80,
            "clicked": 70
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/template-analytics?template_ids=[458951126288937]&start=2024-11-10&end=2024-11-14&page_size=100&cursor=c2VsZj1udWxs"
      }
   }
}

Análise de preços

A análise de preços permite que você obtenha detalhes sobre preços e informações sobre faixas de preços para qualquer mensagem entregue dentro de um intervalo de datas especificado.

Exemplo de solicitação

Para obter análises de preços, envie uma solicitação GET para o seguinte endpoint, substituindo waba_id com o ID da conta do WhatsApp Business para a qual você deseja obter os dados analíticos dos modelos:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/pricing-analytics

Os parâmetros de consulta detalhados a seguir podem ser usados para filtrar os resultados:

Nome Tipo Obrigatório Notas
start string(timestamp) Não A data e a hora de início a partir das quais os dados analíticos serão recuperados, no formato YYYY-MM-DD.
end string(timestamp) Não A data e a hora finais até as quais os dados analíticos devem ser recuperados, no formato YYYY-MM-DD.
granularity sequência de caracteres Não Deve ser um dos HALF_HOUR, DAILY, ou MONTHLY.
phone_numbers matriz Não Números de telefone para os quais você deseja obter dados analíticos. Se não forem especificados, serão exibidos os dados analíticos de todos os números de telefone associados ao WABA. Exemplo: [ "16505550111" ]
country_codes matriz Não Códigos de país de duas letras para os países dos quais você deseja obter dados analíticos. Se não forem especificados, serão exibidos os dados analíticos de todos os países. Exemplo: [ "US" ]
dimensions matriz Não Lista de critérios de segmentação que você deseja aplicar às suas métricas. Se estiver vazia, todos os resultados serão exibidos sem qualquer segmentação. Pode incluir PRICING_CATEGORY, PRICING_TYPE, COUNTRY, PHONE, e TIER.
tier matriz Não O valor da propriedade “tier” representa a concatenação dos limites inferior e superior para o nível específico do par mercado-categoria (país e pricing_category). Exemplo: [ "0:100000" ]

Exemplo de resposta

{
   "granularity": "DAILY",
   "product_type": "cloud_api",
   "_embedded": {
      "pricing_analytics": [
         {
            "start": "2024-11-11T00:00:00Z",
            "end": "2024-11-11T00:00:00Z",
            "volume": 100,
            "phone_number": "14155552671",
            "country": "US",
            "tier": "75000:150000",
            "pricing_type": "REGULAR",
            "pricing_category": "AUTHENTICATION"
         }
      ]
   },
   "paging": {
      "cursors": {
         "before": "MjQZD",
         "after": "MAZDZD"
      },
      "previous": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MjQZD",
      "next": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MAZDZD"
   }
}

Exemplo de solicitação com parâmetros de consulta

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/waba111/pricing-analytics?start=2026-01-25T15:07:24.850718Z&end=2026-02-14T15:07:24.850838Z&granularity=DAILY&country_codes=['IN','US']&dimensions=['PRICING_CATEGORY', 'PRICING_TYPE', 'COUNTRY', 'PHONE', 'TIER']&phone_numbers=16505550111,16505550112,16505550113&pricing_categories=['Utility']&pricing_types=['REGULAR']

Exemplo de resposta com parâmetros de consulta

{
  "id": "345688589250625",
  "granularity": "DAILY",
  "product_type": "cloud_api",
  "_embedded": {
    "pricing_analytics": [
      {
        "start": "2025-06-06T07:00:00Z",
        "end": "2025-06-07T07:00:00Z",
        "country": "IN",
        "pricing_type": "FREE_CUSTOMER_SERVICE",
        "pricing_category": "SERVICE",
        "volume": 2
      },
      {
        "start": "2025-06-05T07:00:00Z",
        "end": "2025-06-06T07:00:00Z",
        "country": "IN",
        "pricing_type": "REGULAR",
        "pricing_category": "AUTHENTICATION_INTERNATIONAL",
        "volume": 2,
        "tier": "0:750000"
      },
      {
        "start": "2025-06-05T07:00:00Z",
        "end": "2025-06-06T07:00:00Z",
        "country": "IN",
        "pricing_type": "FREE_CUSTOMER_SERVICE",
        "pricing_category": "SERVICE",
        "volume": 2
      },
      {
        "start": "2025-06-03T07:00:00Z",
        "end": "2025-06-04T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "MARKETING",
        "volume": 1,
        "tier": "0:MAX"
      },
      {
        "start": "2025-06-02T07:00:00Z",
        "end": "2025-06-03T07:00:00Z",
        "country": "US",
        "pricing_type": "FREE_CUSTOMER_SERVICE",
        "pricing_category": "SERVICE",
        "volume": 1
      },
      {
        "start": "2025-06-02T07:00:00Z",
        "end": "2025-06-03T07:00:00Z",
        "country": "US",
        "pricing_type": "FREE_ENTRY_POINT",
        "pricing_category": "SERVICE",
        "volume": 6
      },
      {
        "start": "2025-06-02T07:00:00Z",
        "end": "2025-06-03T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "AUTHENTICATION",
        "volume": 1,
        "tier": "0:2"
      },
      {
        "start": "2025-06-02T07:00:00Z",
        "end": "2025-06-03T07:00:00Z",
        "country": "IN",
        "pricing_type": "REGULAR",
        "pricing_category": "AUTHENTICATION_INTERNATIONAL",
        "volume": 1,
        "tier": "0:750000"
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "FREE_CUSTOMER_SERVICE",
        "pricing_category": "SERVICE",
        "volume": 2
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "AUTHENTICATION",
        "volume": 1,
        "tier": "0:2"
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "FREE_CUSTOMER_SERVICE",
        "pricing_category": "UTILITY",
        "volume": 1
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "UTILITY",
        "volume": 1,
        "tier": "0:2"
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "MARKETING",
        "volume": 4,
        "tier": "0:MAX"
      },
      {
        "start": "2025-06-01T07:00:00Z",
        "end": "2025-06-02T07:00:00Z",
        "country": "US",
        "pricing_type": "REGULAR",
        "pricing_category": "MARKETING_LITE",
        "volume": 1,
        "tier": "0:MAX"
      }
    ]
  }
}

Leitura complementar