Come visualizzare le metriche dell'account WhatsApp nella tua app

L'API Business Management di WhatsApp ti consente di accedere a metriche e dati statistici relativi al tuo account WhatsApp Business (WABA). Puoi ottenere due tipi di dati sul tuo account:

• Dati statistici per i messaggi: il numero di messaggi inviati e consegnati dai numeri di telefono associati a uno specifico account WhatsApp Business in un determinato periodo.
• Dati statistici per le conversazioni: informazioni relative a conversazioni e costi per i messaggi inviati in un determinato periodo.

Quando esegui una query sull'endpoint dell'API, devi specificare se desideri ottenere i dati statistici per i messaggi o le conversazioni aggiungendo analytics oppure conversation_analytics come parametro per l'URL.

Questa è una richiesta di esempio per ottenere dati statistici sui messaggi del tuo account:

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

In questo esempio, abbiamo specificato che vogliamo recuperare i dati statistici sui messaggi per i numeri di telefono collegati all'account WhatsApp Business che ha un ID univoco. Nella sezione Requisiti seguente sono riportate maggiori informazioni sull'ottenimento dell'ID dell'account WhatsApp Business e del token d'accesso.

Inoltre, quando effettui una richiesta, puoi applicare parametri di filtro per affinare il risultato. L'endpoint dell'API Business Management supporta in totale sei parametri di filtro. Devi avere i parametri seguenti:

• start: se specifichi una data di inizio, la risposta non include i messaggi inviati prima della data specificata.

• end: se specifichi una data di fine, la risposta non include i messaggi inviati dopo la data specificata.

• granularity: quanto desideri siano granulari i dati statistici recuperati? Valori possibili sono HALF_HOUR, DAY e MONTH.

Per quanto riguarda conversation_analytics, hai nove parametri di filtro, di cui tre ( start, end e granularity ) obbligatori.

Requisiti

Per questo tutorial, dovrai:

• installare Python e pip sulla macchina di sviluppo locale*;

• iscriverti per ottenere un account sviluppatore su Meta for Developers, creare un'app di tipo business e aggiungere all'app un account WhatsApp Business;

• eseguire la configurazione (sulla pagina Aggiungi prodotti alla tua app, clicca sul pulsante Configura sull'opzione WhatsApp).

Dopo aver creato un'app di tipo WhatsApp Business, otterrai l'ID dell'account WhatsApp Business e un token d'accesso temporaneo. Queste due chiavi ti serviranno per il resto di questo tutorial, quindi conservale.

Puoi aggiungere il tuo numero WhatsApp personale come mittente o utilizzare il numero di telefono di prova fornito da WhatsApp.

Creazione di un'app Python per visualizzare i dati

Configura un ambiente di sviluppo Python e installa i pacchetti richiesti.

Crea una cartella, assegnale un nome e quindi accedi alla cartella utilizzando uno strumento da riga di comando. Per questo blog, utilizzeremo la libreria requests per effettuare richieste HTTP e la popolare libreria Matplotlib per creare visualizzazioni statiche, animate e interattive. Esegui il comando seguente per installarle:

pip install requests matplotlib

Ora potrai utilizzare le richieste Python per interrogare l'API e ottenere dati statistici da WhatsApp e Matplotlib per visualizzare le metriche tracciando un grafico con i punti dati ricevuti dall'API.

Visualizzazione del numero di messaggi inviati al giorno

Inizia richiedendo i dati statistici. Per farlo, crea un file denominato sent.py nella cartella dell'app e importa le dipendenze necessarie per questo task:

import datetime
import requests
import matplotlib.pyplot as plt

Quindi, crea la richiesta API GET per ottenere i dati statistici utilizzando l'ID del tuo account WhatsApp Business e il token d'accesso. Questi valori sono riportati sulla dashboard del tuo account sviluppatore su Meta for Developers. Il codice della richiesta GET è il seguente:

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)

Nella richiesta precedente, abbiamo rappresentato la data di inizio in stile UNIX, come richiesto dall'API. Puoi utilizzare questo convertitore gratuito per effettuare la conversione tra marche temporali in formato leggibile e UNIX. Il codice converte la risposta in formato JSON nell'ultima riga e la stampa.

Invia il comando seguente per eseguire il codice:

python app.py

Se i numeri di telefono collegati all'account WhatsApp Business vengono utilizzati per inviare messaggi nell'intervallo di tempo specificato, otteniamo un oggetto response del dizionario simile al seguente:

{
  "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"
}

In questo caso, la lista data_points contiene quattro dizionari. Ciascuno contiene il numero di messaggi che i numeri WhatsApp collegati hanno inviato e consegnato durante l'intervallo di date specificato.

Ora che hai i dati, devi recuperare le informazioni necessarie. Poiché vogliamo visualizzare il numero di messaggi inviati ogni giorno, dobbiamo ottenere i valori start e sent da ogni dizionario.

Per farlo, devi eseguire un loop nella lista di punti dati usando il for...in di Python. Converti l'ora di inizio dallo stile UNIX in una versione in formato leggibile per ogni oggetto data. Quindi, ottieni solo il giorno numerico del mese e aggiungilo alla lista dei giorni. Memorizza il numero di messaggi inviati in un'altra lista denominata 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()

Qui tracciamo un grafico di base con i giorni lungo l'asse x e il numero di messaggi inviati lungo l'asse y.

Salva il file ed esegui il codice. Se sei su Linux e ricevi l'errore seguente:

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

Assicurati che tkinter sia installato. Se non lo è, esegui il comando seguente per installarlo:

sudo apt-get install python3-tk

Se esegui il codice, otterrai un grafico simile a questo:

Successivamente, creerai un grafico per visualizzare il numero di messaggi consegnati.

Visualizzazione delle informazioni per un numero WhatsApp specifico

Nella sezione precedente, nella richiesta non abbiamo incluso i numeri di telefono. Di conseguenza, l'API ha restituito informazioni per tutti i numeri di telefono collegati all'account WhatsApp Business entro le date di inizio e di fine specificate.

Se desideri però recuperare i dati statistici per uno o più numeri di telefono, ma non per tutti, devi inserire tali numeri di telefono in un array e passarlo al metodo .phone_numbers quando crei la richiesta:

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}')

Il codice rimanente in sent.py rimane invariato. Quando lo esegui, ottieni i dati statistici solo per i numeri di telefono specificati.

Visualizzazione del numero di messaggi consegnati al giorno

Nelle ultime due sezioni, abbiamo tracciato un grafico per visualizzare il numero di messaggi inviati ogni giorno dai numeri di telefono collegati tramite WhatsApp. Ora tracciamo un grafico per visualizzare il numero di messaggi consegnati giornalmente.

Crea un nuovo file e chiamalo delivered.py. Quindi, copia il codice da sent.py in delivered.py.

Ora apporta alcune modifiche al codice in delivered.py. In primo luogo, rinomina la variabile in alto da no_of_msgs_sent in no_of_msgs_del per riflettere il tipo di dati che intendi memorizzare.

Quindi, nel loop for...in modifica il valore nel metodo point.get da sent in delivered. Ecco uno snippet di come dovrebbe apparire il codice dopo aver apportato le modifiche:

# 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()

Dopo aver eseguito il codice sul terminale (con python delivered.py), otterrai un grafico simile al seguente.

Ora che hai rappresentato due serie di dati statistici per i messaggi, rappresenterai il costo dei messaggi utilizzando conversation_analytics.

Visualizzazione del costo dei messaggi inviati al giorno

Crea un nuovo file per questa sezione denominato cost.py. Copia il codice da sent.py in cost.py. Ora apportiamo alcune modifiche.

In primo luogo, modifica il codice della richiesta. Poiché intendi ottenere informazioni sulle conversazioni, imposta il parametro fields su conversation_analytics e imposta granularity su 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}')

Il campo conversation_anaytics supporta molti altri parametri di filtro per ottenere altri tipi di informazioni. Per maggiori informazioni, leggi la documentazione completa.

Dopo aver effettuato la richiesta precedente, dovresti ottenere un oggetto response molto simile al seguente:

{
  "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
          }
        ]
    }
  },
}

Come già visto, i data_points sono all'interno del dizionario data. Ogni punto dati nel dizionario contiene l'importo e il costo della conversazione.

Quindi, in cost.py, modifica la variabile in alto da no_of_msgs_del in cost_of_convo. Nel loop for...in modifica il valore nel metodo point.get da delivered in cost. Ecco uno snippet di come dovrebbe apparire il codice dopo aver apportato le modifiche:

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 esegui il codice usando il terminale (con python cost.py), otterrai un grafico simile al seguente:

E il gioco è fatto!

Per andare oltre, puoi seguire lo stesso metodo per visualizzare altre metriche fornite dall'API Business Management di WhatsApp.

Conclusioni

In questo tutorial, abbiamo utilizzato la libreria di visualizzazione dei dati matplotlib per visualizzare i dati che mostrano il numero di messaggi inviati al giorno, il numero di messaggi consegnati al giorno e il costo di ogni conversazione.

L'API Business Management di WhatsApp mette a tua disposizione questi parametri di filtro e molti altri, che puoi utilizzare per specificare le metriche che desideri in ogni richiesta. Per maggiori informazioni, consulta la documentazione completa dell'API.

L'API Business Management di WhatsApp fornisce agli sviluppatori informazioni e metriche rilevanti sull'account WhatsApp dei loro utenti. Ad esempio, puoi mostrare ai tuoi utenti sulla loro dashboard il numero di messaggi WhatsApp che hanno inviato in un determinato giorno.

Le possibilità sono infinite!