Como visualizar métricas da conta do WhatsApp no seu app

A API de Gerenciamento do WhatsApp Business dá acesso a métricas e análises sobre a sua conta do WhatsApp Business (WABA, pelas iniciais em inglês). É possível obter dois tipos de dados sobre a conta:

• Análise de mensagens – o número de mensagens enviadas e entregues por números de telefone associados a uma WABA específica em determinado período.
• Análise de conversas – as informações de conversa e custo de mensagens enviadas em determinado período.

Ao consultar o ponto de extremidade da API, é preciso especificar se você quer a análise de mensagens ou de conversas. Para isso, adicione analytics ou conversation_analytics como parâmetro da URL.

Veja este exemplo de solicitação para obter a análise de mensagens da conta:

https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .{filtering-parameters}
      &{access-token}

No exemplo, especificamos que queremos recuperar a análise de mensagens dos números de telefone vinculados à WABA que tem uma identificação única. A seção Requisitos trará mais informações sobre como obter a identificação da WABA e o token de acesso.

Além disso, ao fazer uma solicitação, é possível aplicar parâmetros de filtragem para refinar o resultado. O ponto de extremidade da API de Gerenciamento do WhatsApp Business é compatível com seis parâmetros de filtragem. É preciso ter o seguinte:

• start – se você especificar uma data de início, a resposta não incluirá mensagens enviadas antes dessa data.

• end – se você especificar uma data de término, a resposta não incluirá mensagens enviadas depois dessa data.

• granularity – use esse parâmetro para definir o nível de detalhamento da análise recuperada. Os valores possíveis incluem HALF_HOUR, DAY e MONTH.

Quanto a conversation_analytics, há nove parâmetros de filtragem. Três deles são obrigatórios: start, end e granularity .

Requisitos

Neste tutorial, você precisará fazer o seguinte:

• Instale o Python e o pip na sua máquina de desenvolvedor local.*

• Faça uma conta de desenvolvedor na Meta for Developers, crie um app do tipo Empresa e adicione uma conta do WhatsApp Business ao app.

• Faça a configuração. Na página do seu aplicativo, vá até Adicionar produto e clique no botão Configurar na opção WhatsApp.

Depois de criar um app do tipo WhatsApp Business, você receberá uma identificação da WABA e um token de acesso temporário. Guarde essas duas chaves, pois elas são necessárias para concluir o tutorial.

Você pode adicionar seu número pessoal do WhatsApp como remetente ou usar o número de telefone de teste fornecido pelo WhatsApp.

Criar um app Python para visualizar dados

Configure um ambiente de desenvolvimento Python e instale os pacotes necessários.

Crie uma pasta, dê um nome e navegue até ela por meio de uma ferramenta de linha de comando. Nesta publicação de blog, usaremos a biblioteca de solicitações para fazer solicitações HTTP e a popular biblioteca Matplotlib para criar visualizações estáticas, animadas e interativas. Execute o seguinte comando para instalá-las:

pip install requests matplotlib

Agora será possível usar solicitações Python para consultar a API em busca de dados analíticos do WhatsApp. Depois, use o Matplotlib para visualizar as métricas, traçando um gráfico com os pontos de dados recebidos da API.

Visualizar o número de mensagens enviadas por dia

Comece solicitando os dados analíticos. Para fazer isso, crie um arquivo chamado sent.py na pasta do aplicativo e importe as dependências necessárias para essa tarefa:

import datetime
import requests
import matplotlib.pyplot as plt

Depois, use a identificação da WABA e o token de acesso para criar a solicitação GET da API e obter a análise. Esses valores podem ser encontrados no painel da sua conta de desenvolvedor na Meta for Developers. O código da solicitação GET é o seguinte:

key = 'put-your-access-token-here'
waba_id = 'put-your-waba-id-here'

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).granularity(DAY)&access_token={key}')

dict = res.json() 
print(dict)

Na solicitação acima, representamos a data de início no estilo UNIX, conforme exigido pela API. Use este conversor gratuito para converter registros de data e hora legíveis por humanos em registros UNIX e vice-versa. O código converte a resposta em formato JSON na última linha e a imprime.

Execute o seguinte comando para que o código seja executado:

python app.py

Se os números de telefone vinculados à WABA forem usados para enviar mensagens no período especificado, receberemos um objeto de dicionário de resposta semelhante ao seguinte:

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",

    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1662174000,
        "end": 1662260400,
        "sent": 199251,
        "delivered": 183001
      },
      {
        "start": 1662260400,
        "end": 1662346800,
        "sent": 162489,
        "delivered": 141234
      },
      {
        "start": 1662346800,
        "end": 1662433200,
        "sent": 67902,
        "delivered": 53902
      },
      {
        "start": 1662433200,
        "end": 1662519600,
        "sent": 129521,
        "delivered": 117832
      }
    ]
  },
  "id": "952305634918047"
}

Nesse caso, a lista de data_points contém quatro dicionários. Cada um contém a quantidade de mensagens que os números do WhatsApp vinculados enviaram e entregaram no intervalo de datas especificado.

Agora que você tem os dados, é preciso recuperar as informações necessárias. Como nosso objetivo é visualizar o número de mensagens enviadas em cada dia, precisamos obter os valores start e sent de cada dicionário.

Para fazer isso, processe os pontos de dados usando o loop for...in do Python. Para cada objeto de dados, converta a hora de início no estilo UNIX em uma versão legível por humanos. Depois, obtenha somente o número do dia do mês e adicione-o à lista de dias. Armazene o número de mensagens enviadas em outra lista chamada no_of_msgs_sent:

days = []
no_of_msgs_sent = []

data_points = dict.get("analytics").get("data_points")

for point in data_points:
    
    # Get date in human readable format
    x = datetime.datetime.fromtimestamp(point.get('start'))
    
    # Get just the day in string format
    y = x.strftime("%d")
    
    days.append(y)
    
    # Add the number of sent messages to the list 
    no_of_msgs_sent.append(point.get('sent'))
    
print(days)
print(no_of_msgs_sent)

If you run the code, you get two lists:

['03', '04', '05', '06'] // days
[196093, 147649, 61988, 132465] // number of messages

Now that you have what you need, it's time to visualize it. Add the following code to app.py:

plt.plot(days, no_of_msgs_sent)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages sent')

plt.show()

Aqui, você está traçando um gráfico básico com os dias no eixo X e o número de mensagens enviadas no eixo Y.

Salve o arquivo e execute o código. Se você estiver no Linux, talvez receba o seguinte erro:

UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.

Se esse for o caso, verifique se você tem o Tkinter instalado. Caso contrário, execute o seguinte comando para instalá-lo:

sudo apt-get install python3-tk

Se você executar o código, obterá um gráfico parecido com este:

Depois, você criará um gráfico para visualizar o número de mensagens entregues.

Visualizar informações de um número específico do WhatsApp

Na seção anterior, não incluímos números de telefone na solicitação. Como resultado, a API retornou informações de todos os números de telefone vinculados à WABA nas datas de início e término especificadas.

No entanto, se você quiser recuperar dados analíticos de um ou vários números de telefone, mas não de todos eles, precisará colocar os números correspondentes em uma matriz e passá-la pelo método .phone_numbers ao criar a solicitação:

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).phone_numbers([16505550111, // others]).granularity(DAY)&access_token={key}')

O código restante em sent.py permanecerá o mesmo. Você só obterá a análise dos números especificados ao executar o código.

Visualizar o número de mensagens entregues por dia

Nas duas últimas seções, traçamos um gráfico para visualizar o número de mensagens enviadas diariamente pelos números de telefone vinculados via WhatsApp. Agora, vamos traçar um gráfico para visualizar a quantidade de mensagens entregues diariamente.

Crie um arquivo e dê o nome de delivered.py. Depois, cole o código de sent.py em delivered.py.

Depois, faça algumas alterações no código em delivered.py. Primeiro, altere o nome da variável na parte de cima de no_of_msgs_sent para no_of_msgs_del , de modo a refletir o tipo de dado que você está armazenando.

Depois, no loop for...in , altere o valor no método point.get de sent para delivered. Aqui está um trecho de como seu código deve ficar depois de fazer as alterações:

# Variables go here

for point in data_points:
    
    # Code for getting human readable date goes here    
    
    # Now add the number of delivered messages to the list  
    no_of_msgs_del.append(point.get('delivered'))

print(day)
print(no_of_msgs_del)

Finally, specify no_of_msgs_del in the plt.plot method and update the label shown on the y-axis:

plt.plot(days, no_of_msgs_del)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages delivered')

plt.show()

Depois de executar o código no seu terminal (com python delivered.py), você obterá um gráfico como este.

Agora que você representou dois conjuntos de dados analíticos para as mensagens, é preciso representar o custo das mensagens usando conversation_analytics.

Visualizar o custo de mensagens enviadas por dia

Mais uma vez, crie um arquivo para esta seção e dê o nome cost.py. Cole o código de sent.py em cost.py. Agora, vamos fazer algumas mudanças.

Primeiro, modifique o código de solicitação. Já que vamos obter as informações de conversa, defina o parâmetro fields como conversation_analytics e defina granularity como daily.

res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=conversation_analytics.start(1662174000).end(1662548446).granularity(DAILY).phone_numbers([])&access_token={key}')

O campo conversation_anaytics é compatível com diversos outros parâmetros de filtragem, permitindo obter outros tipos de informações. Para saber mais, leia a documentação completa.

Depois de fazer a solicitação acima, você receberá um objeto de resposta muito semelhante ao seguinte:

{
  "conversation_analytics": {
    'data': {
        "data_points": [
          {
            "start": 1662174000,
            "end": 1662260400,
            "conversation": 5250,
            "cost": 45.0532
          },
          {
            "start": 1662260400,
            "end": 1662346800,
            "conversation": 2250,
            "cost": 25.0290
          },
          {
            "start": 1662346800,
            "end": 1662433200,
            "conversation": 800,
            "cost": 0.0000
          },
          {
            "start": 1662433200,
            "end": 1662519600,
            "conversation": 3150,
            "cost": 33.2015
          }
        ]
    }
  },
}

Como visto acima, os data_points estão dentro do dicionário de dados. Cada ponto de dados no dicionário tem um valor e um custo de conversa.

Depois, em cost.py, altere a variável na parte de cima de no_of_msgs_del para cost_of_convo. No loop for...in , altere o valor no método point.get de delivered para cost. Aqui está um trecho de como seu código deve ficar depois de fazer as alterações:

days = []
cost_of_convo = []

data_points = dict.get('conversation_analytics').get("data").get("data_points")

for point in data_points:
   
    x = datetime.datetime.fromtimestamp(point.get('start'))   
    y = x.strftime("%d")
    
    days.append(y)
    
    # Add the cost of messages in each data point
    cost_of_convo.append(point.get('cost'))

Now, to plot a graph visualizing it:

plt.plot(days, cost_of_convo)

plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Cost of messages sent')

plt.show()

Se executar o código usando o terminal (com python cost.py), você obterá um gráfico como este:

Pronto!

Se quiser ir além, use o mesmo método para visualizar outras métricas fornecidas pela API de Gerenciamento do WhatsApp Business.

Conclusão

Neste tutorial, usamos a biblioteca de visualização de dados Matplotlib para visualizar dados que mostram o número de mensagens enviadas por dia, o número de mensagens entregues por dia e o custo de cada conversa de mensagens.

A API de Gerenciamento do WhatsApp Business fornece esses parâmetros de filtragem e muitos outros. Você pode usá-los para especificar as métricas desejadas em cada solicitação. Para saber mais, confira a documentação completa da API.

Para desenvolvedores, a API de Gerenciamento do WhatsApp Business fornece informações e métricas relevantes da conta do WhatsApp dos usuários. Por exemplo, é possível mostrar aos usuários o número de mensagens do WhatsApp que eles enviaram em determinado dia no próprio painel.

As possibilidades são infinitas!