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.
Usa l'endpoint WhatsApp Business Account per ottenere dati statistici.
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> ?fields=<FIELDS>.<FILTERING_PARAMETER>
Segnaposto | Descrizione | Valore di esempio |
---|---|---|
| Obbligatorio. Metrica. Il valore può essere uno tra: |
|
| Obbligatorio. Parametro di applicazione di filtri per le metriche. Aggiungi ulteriori parametri di applicazione di filtri usando i puntini. Per i valori possibili, vedi: |
|
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.
Nome | Descrizione (clicca sulla freccia nella colonna di sinistra per le opzioni supportate). |
---|---|
tipo: indicazione temporale UNIX | Obbligatorio. La data di inizio dell'intervallo di date per il quale desideri recuperare i dati statistici. |
tipo: indicazione temporale UNIX | Obbligatorio. La data di fine dell'intervallo di date per il quale desideri recuperare i dati statistici. |
tipo: stringa | Obbligatorio. La granularità con cui desideri recuperare i dati statistici. |
tipo: array | Facoltativo. Un array dei numeri di telefono per i quali desideri recuperare i dati statistici. Se non viene fornito, saranno inclusi tutti i numeri di telefono aggiunti al tuo WABA. |
tipo: array | Facoltativo. I tipi di messaggi (messaggi di notifica e/o messaggi dell'assistenza clienti) per i quali desideri recuperare le notifiche. Fornisci un array e includi |
tipo: array | Facoltativo. I Paesi per i quali desideri recuperare i dati statistici. Fornisci un array con codici di 2 lettere dei Paesi che desideri includere. Se non viene fornito, saranno restituiti i dati statistici per tutti i Paesi con cui hai comunicato. |
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/v20.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" }
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.
Nome | Descrizione (clicca sulla freccia nella colonna di sinistra per le opzioni supportate). |
---|---|
tipo: indicazione temporale UNIX | Obbligatorio. La data di inizio dell'intervallo di date per il quale desideri recuperare i dati statistici. |
tipo: indicazione temporale UNIX | Obbligatorio. La data di fine dell'intervallo di date per il quale desideri recuperare i dati statistici. |
tipo: stringa | Obbligatorio. La granularità con cui desideri recuperare i dati statistici. |
tipo: array | Facoltativo. Un array dei numeri di telefono per i quali desideri recuperare i dati statistici. Se non viene fornito, saranno inclusi tutti i numeri di telefono aggiunti al tuo account WhatsApp Business. |
| Facoltativo. Lista di metriche che desideri ricevere. Se invii una lista vuota, restituiremo risultati relativi a tutti i tipi di metriche. |
| Facoltativo. Lista di categorie di conversazioni. Se invii una lista vuota, restituiremo risultati relativi a tutte le categorie di conversazioni. |
| Facoltativo. Lista di tipi di conversazioni. Se invii una lista vuota, restituiremo risultati relativi a tutti i tipi di conversazioni. |
| Facoltativo. Lista in cui è riportato chi ha avviato le conversazioni. Se invii una lista vuota, restituiremo risultati relativi a tutte le opzioni di avvio di una conversazione. |
| Facoltativo. Lista di dettagli che desideri applicare alle tue metriche. Se invii una lista vuota, restituiremo risultati senza alcun dettaglio. |
I dati statistici sono approssimativi e possono differire da quanto indicato sulle fatture a causa di piccole variazioni nell'elaborazione dei dati.
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.
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/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}"
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", }
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_CATEGORY
CONVERSATION_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/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"
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" }
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, esegui una richiesta 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}"
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 } ] } ] }
Richiesta:
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}"
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" }
Richiesta:
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}"
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" }
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.
MARKETING
o UTILITY
.Per segnalare eventuali bug dei dati statistici sui modelli, invia un ticket all'Assistenza diretta con le seguenti selezioni:
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 }
Nome | Descrizione | Valore di esempio |
---|---|---|
Marca temporale UNIX | Obbligatorio. Data e ora di inizio dell'intervallo di date per il quale desideri recuperare i dati statistici. Dal momento che i dati statistici sui modelli vengono forniti con una granularità giornaliera nel fuso orario UTC, data e ora di inizio diverse dalle 0:00 UTC sarebbero corrette alle 0:00 UTC precedenti. |
|
Indicazione temporale UNIX | Obbligatorio. La data di fine dell'intervallo di date per il quale desideri ottenere i dati statistici. Dal momento che i dati statistici sui modelli vengono forniti con una granularità giornaliera nel fuso orario UTC, data e ora di fine diverse dalle 0:00 UTC sarebbero corrette alle 0:00 UTC successive. |
|
Enum | Obbligatorio. La granularità con cui desideri recuperare i dati statistici. Il valore deve essere |
|
Array di ID | Obbligatorio. Un array degli ID dei modelli per i quali desideri recuperare i dati statistici. Massimo 10. |
|
Array di enum | Facoltativo. Il nodo I tipi di metriche che desideri recuperare. Se omesso o fornito un array vuoto, verranno restituiti i dati statistici per tutti i tipi di metriche. Valori possibili:
I clic vengono restituiti solo per i pulsanti URL e i pulsanti di risposta rapida nei modelli categorizzati come Le metriche dei costi vengono restituite come una serie di oggetti di costo, ognuno con un tipo e un valore. I tipi possono essere:
|
|
Scenario: dato un intervallo di tempo di 1 giorno, ottieni tutti i tipi di metriche per i dati analitici dei modelli per un modello di autenticazione e un modello di marketing con un pulsante URL.
Esempio di richiesta:
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...'
Esempio di risposta:
{ "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" } } }
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.
POST /<TEMPLATE_ID> ?cta_url_link_tracking_opted_out=<OPT_OUT> &category=<TEMPLATE_CATEGORY>
Segnaposto | Descrizione | Valore di esempio |
---|---|---|
ID modello | Obbligatorio. ID del modello. |
|
Booleano | Obbligatorio. Indica se il tracking dei clic sul pulsante del modello è disabilitato. Imposta questo parametro su Questo valore viene impostato a |
|
Stringa | Obbligatorio. Categoria attuale del modello. Se imposti la categoria del modello su un valore diverso dalla categoria attuale, lo stato del modello verrà impostato su |
|
curl -X POST 'https://graph.facebook.com/v20.0
/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'
In caso di azione eseguita correttamente, l'API risponderà con:
{ "success": true }
Per una lista di tutti i possibili valori per ciascun campo, consulta il riferimento per l'API Graph del campo Dati statistici sugli account WhatsApp Business.