Dati statistici

Questo documento descrive come ottenere dati statistici relativi a messaggi, conversazioni e modelli, come il numero di messaggi inviati da un numero di telefono aziendale, il numero di conversazioni e i relativi costi per un account WhatsApp Business (WABA) o il numero di volte che un determinato modello è stato letto.

Solo le metriche relative ai numeri di telefono aziendali e ai modelli associati al tuo WABA al momento della richiesta saranno incluse nelle risposte.

Acquisizione dei dati

Usa l'endpoint WhatsApp Business Account per ottenere dati statistici.

Sintassi della query

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

Parametri della stringa della query

Dati statistici sui messaggi

Il campo analytics fornisce il numero e il tipo di messaggi inviati e consegnati dai numeri di telefono associati a un account WhatsApp Business specifico; per le metriche relative alle conversazioni, consulta Dati statistici sulle conversazioni. Quando chiami /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}, puoi allegare i parametri seguenti.

Parametri dei dati statistici

Esempio

Scenario: devi recuperare il numero di messaggi inviati e consegnati da tutti i numeri di telefono associati al tuo account WhatsApp Business.

Soluzione suggerita:assembla l'URL che desideri chiamare e includi i parametri di filtro seguenti: start, end, granularity. Quindi esegui una richiesta GET a quell'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}"

Se la richiesta è andata a buon fine, la risposta restituisce un oggetto analytics con i dati che hai richiesto:

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

Dati statistici sulle conversazioni

Il campo conversation_analytics fornisce informazioni su costi e conversazioni per un account WhatsApp Business specifico. Quando chiami /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}, puoi allegare i parametri seguenti.

Parametri dei dati statistici sulle conversazioni

Esempi

Una volta specificato un intervallo di tempo, puoi ottenere informazioni su conversazioni e costi associati al tuo account WhatsApp Business. Se lo desideri, puoi filtrare e limitare i risultati. Consulta gli esempi di codice qui sotto.

Acquisizione di dati mensili utilizzando tutti i dettagli

Scenario: vuoi recuperare tutte le informazioni su conversazioni e costi per tutti i numeri di telefono associati a un account WhatsApp Business per un dato mese.

Soluzione suggerita:assembla l'URL che desideri chiamare e includi i parametri di filtro seguenti:

• start: inizio dell'intervallo temporale. In questo caso, l'inizio del mese per cui desideri ottenere le metriche.
• end: fine dell'intervallo temporale. In questo caso, la fine del mese per cui desideri ottenere le metriche.
• granularity: il livello di granularità che desideri abbiano i tuoi punti dati. Nell'esempio sotto utilizziamo MONTHLY, quindi ogni punto dati rappresenta un mese di dati.
• phone_numbers: invia un array vuoto e restituiremo informazioni per tutti i numeri di telefono associati all'account WhatsApp Business.
• dimensions: impostalo su tutti i dettagli disponibili: "CONVERSATION_DIRECTION", "CONVERSATION_TYPE", "COUNTRY" e "PHONE".

In questo caso, non è necessario specificare country_codes, metric_types, conversation_types e conversation_directions. Se non specifichi niente per quei campi, verranno restituite tutte le opzioni disponibili. Una volta configurato l'URL, effettua una richiesta 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}"

Se la richiesta è andata a buon fine, la risposta restituisce un oggetto conversation_analytics con i dati che hai richiesto. Nell'esempio seguente, l'account WhatsApp Business contiene solo un numero di telefono.

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

Acquisizione dei dati per uno specifico numero di telefono utilizzando tutti i dettagli e una granularità di mezz'ora

Scenario: vuoi recuperare tutte le informazioni su conversazioni e costi per uno specifico numero di telefono associato a un account WhatsApp Business per un dato intervallo temporale. Desideri che i risultati includano tutti i dettagli possibili. Hai bisogno che ogni punto dati rappresenti mezz'ora di dati.

Soluzione suggerita:assembla l'URL che desideri chiamare e includi i parametri di filtro seguenti:

• start: inizio dell'intervallo temporale.
• end: fine dell'intervallo temporale.
• granularity: il livello di granularità che desideri abbiano i tuoi punti dati. Nell'esempio sotto utilizziamo HALF_HOUR, quindi ogni punto dati rappresenta mezz'ora di dati.
• phone_numbers: il numero di telefono per cui desideri recuperare le informazioni.
• dimensions: impostalo su tutti i dettagli disponibili: ,CONVERSATION_CATEGORYCONVERSATION_TYPE, COUNTRY e PHONE.

In questo caso, non è necessario specificare country_codes, metric_types, conversation_types o conversation_directions. Se non specifichi niente per quei campi, verranno restituite tutte le opzioni disponibili. Una volta configurato l'URL, effettua una richiesta 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"

Se la richiesta è andata a buon fine, la risposta restituisce un oggetto conversation_analytics con i dati che hai richiesto:

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

Acquisizione di dati mensili utilizzando dettagli per tipo di conversazione

Scenario: vuoi recuperare tutte le informazioni su conversazioni e costi per tutti i numeri di telefono associati a un account WhatsApp Business per un dato intervallo temporale. Desideri filtrare i risultati per tipo di conversazione.

Soluzione suggerita:assembla l'URL che desideri chiamare e includi i parametri di filtro seguenti:

• start: inizio dell'intervallo temporale.
• end: fine dell'intervallo temporale.
• granularity: il livello di granularità che desideri abbiano i tuoi punti dati. Nell'esempio sotto utilizziamo MONTHLY, quindi ogni punto dati rappresenta metà mese di dati.
• phone_numbers: invia un array vuoto e restituiremo informazioni per tutti i numeri di telefono associati all'account WhatsApp Business.
• dimensions: impostalo su CONVERSATION_TYPE.

In questo caso, non è necessario specificare country_codes, metric_types, conversation_types, conversation_directions o conversation_categories. Se non specifichi niente per quei campi, verranno restituite tutte le opzioni disponibili. Una volta configurato l'URL, effettua una richiesta 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}"

Se la richiesta è andata a buon fine, la risposta restituisce un oggetto conversation_analytics con i dati che hai richiesto:

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

Acquisizione di mezz'ora di dati suddivisi per categoria di conversazione

Richiesta:

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

Risposta:

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

#### Acquisizione di mezz'ora di dati suddivisi per tipo di conversazione e categoria di conversazione

Richiesta:

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

Risposta:

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

Dati statistici sui modelli

I dati statistici sui modelli descrivono il numero di volte che un modello è stato inviato, consegnato e letto e il numero di volte che i pulsanti URL o i pulsanti di risposta rapida nel modello sono stati cliccati.

I dati vengono restituiti con una granularità giornaliera nel fuso orario UTC con un periodo di registrazione fino a 90 giorni. I dati statistici sui modelli sono disponibili anche nella scheda WhatsApp Manager > Modelli di messaggi > Dettagli del modello > Insight.

Limitazioni

• I dati statistici dei modelli sono disponibili solo per l'API On-Premises se l'account non ha attivato i dati statistici dei modelli dell'API Cloud.
• I dati analitici dei modelli dell'API On-Premises sono soggetti alle linee guida sull'aggregazione e sull'anonimizzazione, che richiedono che si verifichino almeno 1000 eventi prima che il conteggio venga mostrato all'utente.
• I dati statistici sui clic sul pulsante sono disponibili solo per i modelli categorizzati come MARKETING o UTILITY.
• Gli account WABA di proprietà o condivisi con account business di Meta nell'Unione europea, nel Regno Unito o in Giappone, o che hanno un numero di telefono aziendale con prefisso internazionale di uno dei quei Paesi o aree geografiche, non sono supportati.

Segnalazione di bug

Per segnalare eventuali bug dei dati statistici sui modelli, invia un ticket all'Assistenza diretta con le seguenti selezioni:

• Argomento della domanda: WABiz: Cloud API (WhatsApp Business: API Cloud)
• Tipo di richiesta: Bug o problema di implementazione

Conferma dei dati statistici sui modelli

Devi confermare i dati statistici sui modelli sul tuo account WhatsApp Business prima di poter ottenere dati statistici sui modelli. Puoi confermare i dati statistici sui modelli usando WhatsApp Manager o l'API. Per confermare tramite API, invia la seguente richiesta:

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

Una volta confermato, inizieremo ad acquisire i dati statistici sui modelli per l'account WhatsApp Business. Una volta confermato, i dati statistici sui modelli non possono essere disabilitati.

In caso di azione eseguita correttamente, l'API risponderà con l'ID del tuo account WhatsApp Business. Ad esempio:

{                          
  "id": 102290129340398
}

Parametri dei dati statistici sui modelli

Esempi

Acquisizione di tutti i dati statistici sui modelli

Scenario: una volta specificato un periodo di 2 giorni, ottieni tutti i dati statistici sui modelli disponibili per un singolo modello di messaggio associato a un account WhatsApp Business.

Esempio di richiesta:

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...'

Esempio di risposta:

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

Dati statistici sulla disabilitazione dei clic sul pulsante

Puoi disabilitare il tracking dei clic sul pulsante su uno specifico modello impostandone il campo cta_url_link_tracking_opted_out su true. Una volta disabilitata, l'API non restituirà più la proprietà cliccata nei dati statistici sui modelli né visualizzerà i clic/le interazioni con il pulsante in WhatsApp Manager quando visualizzi gli insight del modello.

Sintassi della richiesta

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

Parametri della richiesta

Esempio di richiesta

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

Esempio di risposta

In caso di azione eseguita correttamente, l'API risponderà con:

{
    "success": true
}

Riferimento

Per una lista di tutti i possibili valori per ciascun campo, consulta il riferimento dell'API Graph del campo Dati statistici sugli account WhatsApp Business.