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.
Use o ponto de extremidade WhatsApp Business Account para obter análises.
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> ?fields=<FIELDS>.<FILTERING_PARAMETER>
Espaço reservado | Descrição | Valor de exemplo |
---|---|---|
| Obrigatório. Métrica. O valor pode ser um destes: |
|
| Obrigatório. Parâmetro de filtragem de métrica. Inclua parâmetros adicionais de filtragem usando pontos. Consulte possíveis valores nestas seções: |
|
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.
Nome | Descrição (clique na seta da coluna da esquerda para ver as opções compatíveis) |
---|---|
Tipo: registro de data e hora UNIX | Obrigatório. É a data de início do intervalo para o qual você está recuperando análises. |
Tipo: registro de data e hora do UNIX | Obrigatório. É a data de término do intervalo para o qual você está recuperando análises. |
Tipo: string | Obrigatório. É o detalhamento desejado para a análise. |
Tipo: matriz | Opcional. É a matriz de números de telefone referentes à análise que você quer recuperar. Caso não seja fornecida, todos os números de telefone adicionados à sua WABA serão incluídos. |
Tipo: matriz | Opcional. São os tipos de mensagens referentes à análise que você quer recuperar (mensagens de notificação e/ou de suporte ao cliente). Forneça uma matriz e inclua |
Tipo: matriz | Opcional. São os países referentes à análise que você quer recuperar. Forneça uma matriz com códigos de duas letras para os países a serem incluídos. Caso a matriz não seja fornecida, retornaremos análises para todos os países com os quais você se comunicou. |
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/v20.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" }
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:
Nome | Descrição (clique na seta da coluna da esquerda para ver as opções compatíveis) |
---|---|
Tipo: registro de data e hora UNIX | Obrigatório. É a data de início do intervalo para o qual você está recuperando análises. |
Tipo: registro de data e hora do UNIX | Obrigatório. É a data de término do intervalo para o qual você está recuperando análises. |
Tipo: string | Obrigatório. É o detalhamento desejado para a análise. |
Tipo: matriz | Opcional. É a matriz de números de telefone referentes à análise que você quer recuperar. Caso não seja fornecida, todos os números de telefone adicionados à sua WABA serão incluídos. |
| Opcional. É a lista de métricas que você quer receber. Se você enviar uma lista vazia, retornaremos resultados para todos os tipos de métrica. |
| Opcional. É uma lista de categorias de conversa. Se você enviar uma lista vazia, retornaremos resultados para todas as categorias de conversa. |
| Opcional. É uma lista de tipos de conversa. Se você enviar uma lista vazia, retornaremos resultados para todos os tipos de conversa. |
| Opcional. É uma lista de direções de conversa. Se você enviar uma lista vazia, retornaremos resultados para todas as direções de conversa. |
| Opcional. É a lista de detalhamentos que você quer aplicar às suas métricas. Se você enviar uma lista vazia, retornaremos os resultados sem detalhamento. |
Os dados de análise são aproximados e podem ser diferentes do que aparece nas faturas devido a pequenas variações no processamento.
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.
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/v20.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", }
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/v20.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" }
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/v20.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 } ] } ] }
Solicitação
curl -i -X GET \
"https://graph.facebook.com/v20.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" }
Solicitação
curl -i -X GET \
"https://graph.facebook.com/v20.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" }
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.
MARKETING
ou UTILITY
.Para relatar bugs nas análises de modelos, abra um tíquete no Suporte Direto e selecione o seguinte:
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 }
Nome | Descrição | Valor de exemplo |
---|---|---|
Registro de data e hora UNIX | Obrigatório. É o registro de data e hora de início do intervalo para o qual você está recuperando análises. As análises de modelos são fornecidas com detalhamento diário no fuso horário UTC. Por isso, registros de data e hora de início em outros horários ou fusos serão corrigidos para a 00:00 UTC anterior. |
|
Registro de data e hora UNIX | Obrigatório. É a data de término do intervalo para o qual você está recuperando análises. As análises de modelos são fornecidas com detalhamento diário no fuso horário UTC. Por isso, registros de data e hora de término em outros horários ou fusos serão corrigidos para a 00:00 UTC seguinte. |
|
Enumeração | Obrigatório. É o detalhamento desejado para a análise. O valor deve ser |
|
Matriz de IDs | Obrigatório. É a matriz de IDs de modelos referentes à análise que você quer recuperar. Máximo de 10. |
|
Matriz de enumerações | Opcional. O nó Os tipos de métricas a serem recuperadas. Se a matriz for omitida ou estiver vazia, serão retornadas as análises de todos os tipos de métricas. Valores possíveis:
Os cliques são retornados apenas para botões URL e de resposta rápida em modelos categorizados como As métricas de custo são retornadas como uma matriz de objetos de custo, cada um com um tipo e valor. Os tipos podem ser:
|
|
Cenário: obtenha todos os tipos de métricas de análise de modelos para um modelo de autenticação e um modelo de marketing com um botão de URL, considerando um período de um dia.
Exemplo de solicitação:
curl -g 'https://graph.facebook.com/v20.0
/109259195336416/template_analytics?start=1718064000&end=1718122745&granularity=daily&metric_types=cost%2Cclicked%2Cdelivered%2Cread%2Csent&template_ids=[1421988012088524%2C2632273056924580]' \
-H 'Authorization: Bearer EAAJB...'
Exemplo de resposta:
{ "data": [ { "granularity": "DAILY", "product_type": "cloud_api", // Only available to businesses in Marketing Messages Lite API alpha "data_points": [ { "template_id": "1421988012088524", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "cost": [ { "type": "amount_spent", "value": 0.01 }, { "type": "cost_per_delivered", "value": 0.01 } ] }, { "template_id": "2632273056924580", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "clicked": [ { "type": "url_button", "button_content": "Contact Support", "count": 1 } ], "cost": [ { "type": "amount_spent", "value": 0.03 }, { "type": "cost_per_delivered", "value": 0.03 }, { "type": "cost_per_url_button_click", "value": 0.03 } ] } ] } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MjQZD" } } }
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.
POST /<TEMPLATE_ID> ?cta_url_link_tracking_opted_out=<OPT_OUT> &category=<TEMPLATE_CATEGORY>
Espaço reservado | Descrição | Valor de exemplo |
---|---|---|
ID do modelo | Obrigatório. O ID do modelo. |
|
Booliano | Obrigatório. Indica se o rastreamento de cliques no botão do modelo foi desabilitado. Defina como Esse valor será definido como |
|
String | Obrigatório. A categoria atual do modelo. Se você definir a categoria do modelo como um valor diferente da opção atual, o status do modelo será definido como |
|
curl -X POST 'https://graph.facebook.com/v20.0
/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'
Se o processo for bem-sucedido, a API enviará a seguinte resposta:
{ "success": true }
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.