Análise

Este documento descreve como obter análises de mensagens, conversas e modelos. Isso inclui o número de mensagens enviadas de um número de telefone comercial, o número de conversas e os respectivos custos para uma conta comercial do WhatsApp (WABA, pelas iniciais em inglês) ou o número de vezes que determinado modelo foi lido.

Somente métricas de números de telefone comercial e modelos associados à sua WABA no momento da solicitação serão incluídas nas respostas.

Como obter dados

Use o ponto de extremidade WhatsApp Business Account para obter análises.

Sintaxe da consulta

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=<FIELDS>.<FILTERING_PARAMETER>

Parâmetros da string de consulta

Análise de mensagens

O campo analytics fornece o número e o tipo de mensagens enviadas e entregues por números de telefone associados a uma WABA específica. Para saber mais sobre métricas de conversa, consulte Análise de conversas. Ao chamar /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}, você pode anexar os parâmetros a seguir.

Parâmetros de análise

Example

Cenário: você precisa obter o número de mensagens enviadas e entregues por todos os números de telefone associados à sua WABA.

Solução sugerida: monte a URL que você quer chamar e inclua os parâmetros de filtragem start, end e granularity. Depois disso, faça uma solicitação GET à URL:

curl -i -X GET \ 
"https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

Uma resposta bem-sucedida retornará um objeto analytics com os dados solicitados:

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",
      "BR"
    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1543543200,
        "end": 1543629600,
        "sent": 196093,
        "delivered": 179715
      },
      {
        "start": 1543629600,
        "end": 1543716000,
        "sent": 147649,
        "delivered": 139032
      },
      {
        "start": 1543716000,
        "end": 1543802400,
        "sent": 61988,
        "delivered": 58830
      },
      {
        "start": 1543802400,
        "end": 1543888800,
        "sent": 132465,
        "delivered": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

Análise de conversas

O campo conversation_analytics fornece informações de custo e conversa para uma WABA específica. Ao chamar /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}, você pode anexar os seguintes parâmetros:

Parâmetros de análise de conversas

Exemplos

Ao definir um período, você pode obter informações de conversas e custos associadas à sua WABA. É possível filtrar e detalhar os resultados. Consulte os exemplos de código abaixo.

Como obter dados mensais usando todos os detalhamentos

Cenário: em um determinado mês, você quer recuperar informações de conversa e custo de todos os números de telefone associados a uma WABA.

Solução sugerida: monte a URL que você quer chamar e inclua estes parâmetros de filtragem.

• start: indica o início do período. Nesse caso, é o início do mês referente às métricas que você quer ver.
• end: indica o término do período. Nesse caso, é o término do mês para o qual você que ver as métricas.
• granularity: representa o detalhamento desejado para os pontos de dados. No exemplo abaixo, usamos MONTHLY para que cada ponto represente o valor de um mês de dados.
• phone_numbers: ao enviar uma matriz vazia, retornaremos informações para todos os números de telefone associados à WABA.
• dimensions: defina todos os detalhamentos disponíveis: "CONVERSATION_CATEGORY", "CONVERSATION_TYPE", "COUNTRY" e "PHONE".

Nesse caso, não é preciso especificar country_codes, metric_types, conversation_types nem conversation_categories. Se você não enviar um valor para esses campos, retornaremos todas as opções disponíveis. Depois de configurar a URL, faça uma solicitação GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800).end(1688194800)
  .granularity(MONTHLY)
  .phone_numbers([])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
  &access_token={access-token}"

Uma resposta bem-sucedida retornará um objeto conversation_analytics com os dados solicitados. No exemplo a seguir, a WABA contém apenas um número de telefone.

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1558,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.58
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2636,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 26.36
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2238,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "SERVICE",
            "cost": 22.38
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1782,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "UTILITY",
            "cost": 17.82
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1568,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.68
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2716,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "MARKETING",
            "cost": 27.16
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2180,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "SERVICE",
            "cost": 21.8
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1465,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "UTILITY",
            "cost": 14.65
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1433,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_ENTRY_POINT",
            "conversation_category": "SERVICE",
            "cost": 14.33
          }
        ]
      }
    ]
  },
  "id": "102290129340398",
}

Como obter dados de um número específico usando todos os detalhamentos e a granularidade de meia hora

Cenário: em um determinado período, você quer recuperar informações de conversa e custo de um número de telefone específico associado a uma WABA. Sua intenção é usar todos os detalhamentos possíveis nos resultados. É preciso que cada ponto represente meia hora de dados.

Solução sugerida: monte a URL que você quer chamar e inclua estes parâmetros de filtragem.

• start: indica o início do período.
• end: indica o término do período.
• granularity: representa o detalhamento desejado para os pontos de dados. No exemplo abaixo, usamos HALF_HOUR para que cada ponto represente o valor de meia hora de dados.
• phone_numbers: o número de telefone sobre o qual você precisa de informações.
• dimensions: defina todos os detalhamentos disponíveis: CONVERSATION_CATEGORY, CONVERSATION_TYPE, COUNTRY e PHONE.

Nesse caso, não é preciso especificar country_codes, metric_types, conversation_types nem conversation_categories. Se você não enviar um valor para esses campos, retornaremos todas as opções disponíveis. Depois de configurar a URL, faça uma solicitação GET:

curl -i -X GET \
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800)
  .end(1685689200)
  .granularity(HALF_HOUR)
  .phone_numbers(["19195552584"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
  &access_token=your-access-token"

Uma resposta bem-sucedida retornará um objeto conversation_analytics com os dados solicitados:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "SERVICE",
            "cost": 0.0232
          },
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "MARKETING",
            "cost": 0.0232
          },
         # ... more data points
        ]
      }
    ]
  },
  "id": "102290129340398"
}

Como obter dados mensais usando detalhamentos de tipo de conversa

Cenário: em um determinado período, você quer recuperar as informações de conversa e custo de todos os números de telefone associados a uma WABA. Sua intenção é detalhar os resultados por tipo de conversa.

Solução sugerida: monte a URL que você quer chamar e inclua estes parâmetros de filtragem.

• start: indica o início do período.
• end: indica o término do período.
• granularity: representa o detalhamento desejado para os pontos de dados. No exemplo abaixo, usamos MONTHLY para que cada ponto represente o valor de meio mês de dados.
• phone_numbers: se você enviar uma matriz vazia, retornaremos informações sobre todos os números de telefone associados à WABA.
• dimensions: defina como CONVERSATION_TYPE.

Nesse caso, não é preciso especificar country_codes, metric_types, conversation_types, conversation_directions nem conversation_categories. Se você não enviar um valor para esses campos, retornaremos todas as opções disponíveis. Depois de configurar a URL, faça uma solicitação GET:

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

Uma resposta bem-sucedida retornará um objeto conversation_analytics com os dados solicitados:

{
  "data": [
    {
      "data_points": [
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation": 8500,
          "conversation_type": "REGULAR",
          "cost": 88.1010
        },
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 1000,
          "conversation_type": "FREE_TIER",
          "cost": 0.0000
        }
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 250,
          "conversation_type": "FREE_ENTRY_POINT",
          "cost": 0.0000
        }
      ]
    }
  ]
}

Como obter dados de meia hora detalhados por categoria de conversa

Solicitação:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY"])
  &access_token={access-token}"  

Resposta:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          },
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_category": "MARKETING",
            "cost": 0.0432
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

#### Como obter dados de meia hora detalhados por tipo e categoria de conversa

Solicitação:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
  &access_token={access-token}"  

Resposta:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 0.0432
          },
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_type": "REGULAR",
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

Análise de modelos

A análise de modelos descreve o número de vezes que um modelo foi enviado, entregue e lido, além da quantidade de cliques que os botões URL ou de resposta rápida receberam no modelo.

Os dados são retornados com detalhamento diário no fuso horário UTC e histórico de até 90 dias. Também é possível encontrar dados de análise de modelos no painel Gerenciador do WhatsApp > Modelos de mensagem > Detalhes do modelo > Insights.

Limitações

• As análises de modelos só estarão disponíveis na API Local se a conta não estiver usando a API de Nuvem para isso.
• As análises de modelos da API Local estão sujeitas às diretrizes de agregação e anonimização, que exigem o mínimo de 1.000 eventos antes que a contagem seja mostrada ao usuário.
• A análise de cliques no botão está disponível apenas para modelos categorizados como MARKETING ou UTILITY.
• Não há compatibilidade com WABAs pertencentes ou compartilhadas com contas empresariais da Meta na União Europeia, no Reino Unido ou no Japão, tampouco com WABAs que tenham um número de telefone comercial com código do país desses locais.

Como relatar bugs

Para relatar bugs nas análises de modelos, abra um tíquete no Suporte Direto e selecione o seguinte:

• Tópico da pergunta: WABiz: Cloud API (WhatsApp Business: API de Nuvem)
• Tipo de solicitação: Problema com bug ou implementação

Como confirmar as análises de modelos

Antes de obter as análises de modelos, é preciso confirmar esse tipo de análise na conta do WhatsApp Business. Isso pode ser feito por meio do Gerenciador do WhatsApp ou da API. Na API, envie esta solicitação:

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

Após isso, começaremos a capturar as análises desse tipo na conta do WhatsApp Business. Depois da confirmação, não é possível desabilitar as análises de modelos.

Caso a solicitação seja bem-sucedida, a API responderá com a identificação da conta do WhatsApp Business. Por exemplo:

{                          
  "id": 102290129340398
}

Parâmetros de análise de modelos

Exemplos

Como obter todas as análises de modelos

Cenário: obter todas as análises sobre um modelo de mensagem específico associado a uma conta do WhatsApp Business para determinado período de dois dias

Exemplo de solicitação:

curl -g 'https://graph.facebook.com/v19.0/109259195336416/template_analytics?start=1689379200&end=1689552000&granularity=DAILY&metric_types=[%27SENT%27%2C%27DELIVERED%27%2C%27READ%27%2C%27CLICKED%27]&template_ids=[1924084211297547%2C954638012257287]' \
-H 'Authorization: Bearer EABN8...'

Exemplo de resposta:

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "1924084211297547",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 3
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 5
            }
          ]
        },
        {
          "template_id": "1924084211297547",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 73
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 35
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 13
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 12
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

Como desabilitar a análise de cliques no botão

Para desabilitar o rastreamento de cliques no botão, defina o campo cta_url_link_tracking_opted_out de um modelo específico como true. Depois que o recurso for desabilitado, a API não retornará mais a propriedade "clicked" na análise do modelo nem exibirá dados de engajamento/cliques no botão no Gerenciador do WhatsApp quando você estiver visualizando os insights do modelo.

Sintaxe da solicitação

POST /<TEMPLATE_ID>
  ?cta_url_link_tracking_opted_out=<OPT_OUT>
  &category=<TEMPLATE_CATEGORY>

Parâmetros da solicitação

Exemplo de solicitação

curl -X POST 'https://graph.facebook.com/v19.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

Se o processo for bem-sucedido, a API enviará a seguinte resposta:

{
    "success": true
}

Referência

Para ver uma lista com todos os possíveis valores de um campo, consulte a referência da Graph API no campo Análise da conta do WhatsApp Business.