In diesem Dokument wird beschrieben, wie du Messaging, Unterhaltungen und Vorlagenanalysen erhalten kannst, wie zum Beispiel die Anzahl der Nachrichten, die von einer Unternehmenstelefonnummer gesendet werden, die Anzahl der Unterhaltungen und deren Kosten für ein WhatsApp-Unternehmenskonto (WhatsApp Business Account, WABA) oder die Häufigkeit, mit der eine bestimmte Vorlage gelesen wurde.
Nur Kennzahlen für Unternehmenstelefonnummern und Vorlagen, die mit deinem WABA zum Zeitpunkt der Anfrage verknüpft sind, werden in Antworten aufgenommen.
Verwenden den WhatsApp Business Account-Endpunkt, um Analysen abzurufen.
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> ?fields=<FIELDS>.<FILTERING_PARAMETER>
Platzhalter | Beschreibung | Beispielwert |
---|---|---|
| Erforderlich. Kennzahl. Der Wert kann einer der Folgenden sein: |
|
| Erforderlich. Parameter zum Filtern Kennzahlen. Hänge weitere Filterparameter an, indem du Punkte verwendest. Mögliche Werte findest du unter: |
|
Das analytics
-Feld enthält die Anzahl und die Art der gesendeten und zugestellten Nachrichten für die jeweils mit einem WABA verknüpften Telefonnummern. Informationen zu Chat-Kennzahlen findest du unter Unterhaltungsanalysen. Bei einem Aufruf von /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}
kannst du folgende Parameter anhängen.
Name | Beschreibung (Klicke für unterstützte Optionen den Pfeil in der linken Spalte.) |
---|---|
Typ: UNIX-Zeitstempel | Erforderlich. Das Startdatum des Zeitraums, für den du Analysen abrufen möchtest. |
Typ: UNIX-Zeitstempel | Erforderlich. Das Enddatum des Zeitraums, für den du Analysen abrufen möchtest. |
Typ: String | Erforderlich. Die Granularität, mit der du die Analysen abrufen möchtest. |
Typ: Array | Optional. Ein Array von Telefonnummern, für die du Analysen abrufen möchtest. Ohne diesen Parameter werden alle Telefonnummern des WABA berücksichtigt. |
Typ: Array | Optional. Die Nachrichtentypen (Benachrichtigungen und/oder Kund*innensupport-Nachrichten), für die du Benachrichtigungen abrufen möchtest. Gib ein Array an und füge |
Typ: Array | Optional. Die Länder, für die du Analysen abrufen möchtest. Gib ein Array mit Ländercodes aus zwei Buchstaben für die Länder an, die du berücksichtigen möchtest. Ohne diesen Parameter werden Analytics für alle Länder zurückgegeben, mit denen du kommuniziert hast. |
Szenario: Du musst die Anzahl der gesendeten und zugestellten Nachrichten für alle mit deinem WABA verknüpften Telefonnummern abrufen.
Vorgeschlagene Lösung:Stelle die URL zusammen, die du aufrufen möchtest und gib die folgenden Filterparameter an: start
, end
, granularity
. Stelle anschließend eine GET
-Anfrage an diese 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}"
Eine erfolgreiche Antwort gibt ein analytics
-Objekt mit den von dir angefragten Daten zurück:
{ "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" }
Das Feld conversation_analytics
liefert Kosten- und Chat-Informationen für einen spezifischen WABA. Bei einem Aufruf von /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}
kannst du folgende Parameter anhängen.
Name | Beschreibung (Klicke für unterstützte Optionen den Pfeil in der linken Spalte.) |
---|---|
Typ: UNIX-Zeitstempel | Erforderlich. Das Startdatum des Zeitraums, für den du Analysen abrufen möchtest. |
Typ: UNIX-Zeitstempel | Erforderlich. Das Enddatum des Zeitraums, für den du Analysen abrufen möchtest. |
Typ: String | Erforderlich. Die Granularität, mit der du die Analysen abrufen möchtest. |
Typ: Array | Optional. Ein Array von Telefonnummern, für die du Analysen abrufen möchtest. Ohne diesen Parameter werden alle Telefonnummern des WABA berücksichtigt. |
| Optional. Liste der Kennzahlen, die du erhalten möchtest. Wenn du eine leere Liste sendest, geben wir Ergebnisse für alle Kennzahltypen zurück. |
| Optional. Liste der Chat-Kategorien. Wenn du eine leere Liste sendest, geben wir Ergebnisse für alle Chat-Kategorien zurück. |
| Optional. Liste der Chat-Typen. Wenn du eine leere Liste sendest, geben wir Ergebnisse für alle Chat-Typen zurück. |
| Optional. Liste der Chat-Richtungen. Wenn du eine leere Liste sendest, geben wir Ergebnisse für alle Chat-Richtungen zurück. |
| Optional. Liste der Aufschlüsselungen, die du auf deine Kennzahlen anwenden möchtest. Wenn du eine leere Liste sendest, geben wir Ergebnisse ohne Aufschlüsselungen zurück. |
Die Analysedaten sind eine Annäherung und können aufgrund von Unterschieden in der Datenverarbeitung von Rechnungsdaten abweichen.
Du kannst für einen entsprechenden Zeitraum Chat- und Kosteninformationen abrufen, die mit deinem WABA zusammenhängen. Wenn du möchtest, kannst du deine Ergebnisse filtern und aufschlüsseln. Sieh dir die Code-Beispiele zur Veranschaulichung an.
Szenario: du möchtest für einen entsprechenden Monat alle Chat- und Kosteninformationen für alle Telefonnummern abrufen, die mit einem WABA zusammenhängen.
Vorgeschlagene Lösung:Stelle die URL zusammen, die du aufrufen möchtest und gib die folgenden Filterparameter an:
start
: Beginn deines Zeitraums. In diesem Fall ist es der Anfang des Monats, für den du die Kennzahlen möchtest.end
: Ende deines Zeitraums. In diesem Fall ist es das Ende des Monats, für den du die Kennzahlen möchtest.granularity
: die Granularität deiner Datenpunkte. In dem untenstehenden Beispiel verwenden wir MONTHLY
, sodass jeder Datenpunkt die Datenmenge eines Monats darstellt.phone_numbers
: Wenn du ein leeres Array sendest, geben wir Informationen für alle Telefonnummern zurück, die mit dem WABA zusammenhängen.dimensions
: Gib alle verfügbaren Aufschlüsselungen an: "CONVERSATION_CATEGORY"
, "CONVERSATION_TYPE"
, "COUNTRY"
und "PHONE"
.In diesem Fall musst du nicht country_codes
, metric_types
, conversation_types
und conversation_categories
spezifizieren. Wenn du uns für diese Felder nichts sendest, geben wir alle verfügbaren Optionen zurück. Sobald du die URL zusammengestellt hast, starte eine GET-Anfrage:
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}"
Eine erfolgreiche Antwort gibt ein conversation_analytics
-Objekt mit den von dir angefragten Daten zurück. Im folgenden Beispiel enthält der WABA lediglich eine Telefonnummer.
{ "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", }
Szenario: Du möchtest für einen entsprechenden Zeitraum alle Chat- und Kosteninformationen für eine bestimmte Telefonnummer abrufen, die mit einem WABA zusammenhängt. In den Ergebnissen solltest du alle möglichen Aufschlüsselungen verwenden. Jeder Datenpunkt soll für die Datenmenge eines halbstündigen Zeitraums stehen.
Vorgeschlagene Lösung: Stelle die URL zusammen, die du aufrufen möchtest und gib die folgenden Filterparameter an:
start
: Beginn deines Zeitraums. end
: Ende deines Zeitraums.granularity
: Die Granularität deiner Datenpunkte. Im untenstehenden Beispiel wird HALF_HOUR
verwendet, sodass jeder Datenpunkt für die Datenmenge eines halbstündigen Zeitraums steht.phone_numbers
: die Telefonnummer, für die du Informationen benötigst.dimensions
: Gib alle verfügbaren Aufschlüsselungen an: CONVERSATION_CATEGORY
, CONVERSATION_TYPE
, COUNTRY
und PHONE
.In diesem Fall musst du nicht country_codes
, metric_types
, conversation_types
oder conversation_categories
spezifizieren. Wenn du uns für diese Felder nichts sendest, geben wir alle verfügbaren Optionen zurück. Sobald du die URL zusammengestellt hast, starte eine GET-Anfrage:
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"
Eine erfolgreiche Antwort gibt ein conversation_analytics
-Objekt mit den von dir angefragten Daten zurück:
{ "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" }
Szenario: Du möchtest für einen entsprechenden Zeitraum alle Chat- und Kosteninformationen für alle Telefonnummern abrufen, die mit einem WABA zusammenhängen. In den Ergebnissen solltest du nach dem Chat-Typ aufschlüsseln.
Vorgeschlagene Lösung: Stelle die URL zusammen, die du aufrufen möchtest, und gib die folgenden Filterparameter an:
start
: Beginn deines Zeitraums. end
: Ende deines Zeitraums.granularity
: die Granularität deiner Datenpunkte. In dem untenstehenden Beispiel verwenden wir MONTHLY
, sodass jeder Datenpunkt die Datenmenge eines Monats darstellt.phone_numbers
: Wenn du ein leeres Array sendest, geben wir Informationen für alle Telefonnummern zurück, die mit dem WABA zusammenhängen.dimensions
: gib CONVERSATION_TYPE
an.In diesem Fall musst du nicht country_codes
, metric_types
, conversation_types
, conversation_directions
oder conversation_categories
spezifizieren. Wenn du uns für diese Felder nichts sendest, geben wir alle verfügbaren Optionen zurück. Sobald du die URL zusammengestellt hast, starte eine GET-Anfrage:
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}"
Eine erfolgreiche Antwort gibt ein conversation_analytics
-Objekt mit den von dir angefragten Daten zurück:
{ "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 } ] } ] }
Anfrage:
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}"
Antwort:
{ "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" }
Anfrage:
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}"
Antwort:
{ "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" }
Vorlagenanalysen geben Auskunft darüber, wie häufig eine Vorlage gesendet, geliefert und gelesen wurde und wie häufig URL-Buttons oder Schnellantwort-Buttons in der Vorlage angeklickt wurden.
Die Daten werden mit einer täglichen Granularität in der UTC-Zeitzone für einen Zeitraum von 90 Tagen angezeigt. Vorlagenanalysen findest du auch im Panel WhatsApp Manager > Nachrichtenvorlagen > Vorlagendetails > Insights.
MARKETING
oder UTILITY
kategorisiert wurden.Um Fehler in Vorlagenanalysen zu melden, übermittle ein Direct Support-Ticket mit den folgenden Angaben:
Du musst Vorlagenanalysen in deinem WhatsApp-Unternehmenskonto bestätigen, bevor du Vorlagenanalysen abrufen kannst. Du kannst Vorlagenanalysen im WhatsApp Manager oder über die API bestätigen. Sende zum Bestätigen über die API die folgende Anfrage:
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true
Nach der Bestätigung beginnen wir mit dem Erfassen von Vorlagenanalysen für das WhatsApp-Unternehmenskonto. Wenn Vorlagenanalysen einmal bestätigt wurden, können sie nicht mehr deaktiviert werden.
War der Vorgang erfolgreich, antwortet die API mit der ID deines WhatsApp-Unternehmenskontos. Beispiel:
{ "id": 102290129340398 }
Name | Beschreibung | Beispielwert |
---|---|---|
UNIX-Zeitstempel | Erforderlich. Der Zeitstempel des Starts, für den du Analysen abrufen möchtest. Da Vorlagenanalysen mit einer Tagesauflösung in UTC-Zeit bereitgestellt werden, wird ein Startzeitstempel, der nicht 0:00 UTC lautet, zu 0:00 UTC korrigiert. |
|
UNIX-Zeitstempel | Erforderlich. Das Enddatum des Zeitraums, für den du Analysen abrufen möchtest. Da Vorlagenanalysen mit einer Tagesauflösung in UTC-Zeit bereitgestellt werden, wird ein Endzeitstempel, der nicht 0:00 UTC lautet, zu 0:00 UTC korrigiert. |
|
Enum | Erforderlich. Die Granularität, mit der du die Analysen abrufen möchtest. Unterstützte Werte:
|
|
Array von IDs | Erforderlich. Ein Array von Vorlagen-IDs, für die du Analysen abrufen möchtest. Maximalwert 10. |
|
Array von Enums | Optional. Die Art von Kennzahlen, die du abrufen möchtest. Wenn kein Wert oder ein leerer Array angegeben wird, werden Analysen für alle Arten von Kennzahlen erstellt. Mögliche Werte:
Klicks werden nur für URL-Buttons und Schnellantwort-Buttons in Vorlagen zurückgegeben, die als |
|
Szenario: Rufe für einen vorgegebenen Zeitraum von zwei Tagen alle verfügbaren Vorlagenanalysen für eine einzige Nachrichtenvorlage, die mit einem WhatsApp-Unternehmenskonto verknüpft ist, ab.
Anfragebeispiel:
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...'
Beispielantwort:
{ "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" } } }
Sie können das Button-Klick-Tracking einer einzelnen Vorlage deaktivieren, indem Sie das Feld cta_url_link_tracking_opted_out
auf true
setzen. Nach der Deaktivierung gibt die API die angeklickte Eigenschaft in der Vorlagenanalyse oder die Display-Button-Interaktionen/Klicks im WhatsApp Manager nicht mehr zurück, wenn die Insights der Vorlage aufgerufen werden.
POST /<TEMPLATE_ID> ?cta_url_link_tracking_opted_out=<OPT_OUT> &category=<TEMPLATE_CATEGORY>
Platzhalter | Beschreibung | Beispielwert |
---|---|---|
Vorlagen-ID | Erforderlich. Vorlagen-ID. |
|
Boolesch | Erforderlich. Gibt an, ob das Vorlagen-Button-Klick-Tracking deaktiviert wurde. Setze den Wert auf Dieser Wert wird bei der Erstellung der Vorlage auf |
|
String | Erforderlich. Aktuelle Kategorie der Vorlage. Wenn du die Vorlagenkategorie auf einen anderen Wert als die aktuelle Kategorie setzt, wird der Vorlagenstatus auf |
|
curl -X POST 'https://graph.facebook.com/v19.0
/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'
Bei Erfolg antwortet die API mit Folgendem:
{ "success": true }
Eine Liste der möglichen Werte für die einzelnen Felder findest du in der Graph API-Referenz für das Analytics-Feld für WhatsApp-Unternehmenskonten.