Analysen

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.

Abrufen der Daten

Verwende den WhatsApp-Unternehmenskonto-Endpunkt, um Analysen abzurufen.

Anfragesyntax

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

Abfrage-String-Parameter

Messaging-Analysen

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.

Analyseparameter

Beispiel

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/v21.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"
}

Chat-Analysen

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.

Unterhaltungsanalyseparameter

Beispiele

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.

Monatliche Daten mithilfe von Aufschlüsselungen abrufen

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/v21.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",
}

Daten für eine bestimmte Telefonnummer mithilfe von Aufschlüsselungen und einer halbstündlichen Granularität abrufen

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/v21.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"
}

Monatliche Daten mithilfe von Chat-Typ-Aufschlüsselungen abrufen

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/v21.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
        }
      ]
    }
  ]
}

Halbstündlich Daten mit Aufschlüsselung nach Chat-Kategorie abrufen

Anfrage:

curl -i -X GET \
 "https://graph.facebook.com/v21.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"
}

Halbstündlich Daten mit Aufschlüsselung nach Chat-Typ und Chat-Kategorie abrufen

Anfrage:

curl -i -X GET \
 "https://graph.facebook.com/v21.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"
}

Preisanalysen

Mithilfe des Felds pricing_analytics kannst Aufschlüsselungen der Preise für alle Nachrichten abrufen, die innerhalb eines bestimmten Datumsbereichs ausgeliefert wurden.

Anfragesyntax

GET /<WABA_ID> ?fields=pricing_analytics .start(<START>) .end(<END>) .granularity(<GRANULARITY>) .phone_numbers(<PHONE_NUMBERS>) .country_codes(<COUNTRY_CODES>) .metric_types(<METRIC_TYPES>) .pricing_types(<PRICING_TYPES>) .pricing_categories(<PRICING_CATEGORIES>) .dimensions(<DIMENSIONS>) 

Parameter

[
  "US",
  "BR"
]

[
  "PRICING_CATEGORY",
  "PRICING_TYPE",
  "COUNTRY"
]

[
  "COST",
  "VOLUME"
]

[
  "15550783881",
  "15550783882",
  "15550783883"
]

[
  "AUTHENTICATION",
  "MARKETING",
  "UTILITY"
]

[
  "REGULAR",
  "FREE_CUSTOMER_SERVICE"
]

Vorlagenanalysen

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.

Einschränkungen

• Vorlagenanalysen sind nur für die On-Premises API verfügbar, wenn das Konto nicht den Vorlagenanalysen der Cloud API zugestimmt hat.
• Vorlagenanalysen der On-Premises API unterliegen den Richtlinien für die Aggregation und Anonymisierung, wonach es mindestens 1.000 Ereignisse geben muss, bevor die Zählung dem*der Benutzer*in angezeigt wird.
• Button-Klick-Analysen sind nur für Vorlagen verfügbar, die als MARKETING oder UTILITY kategorisiert wurden.
• WABAs, die Meta-Unternehmenskonten in der Europäischen Union, im Vereinigten Königreich oder Japan gehören oder mit ihnen geteilt werden oder eine Unternehmenstelefonnummer mit einer Ländervorwahl aus einem dieser Länder oder Regionen haben, werden nicht unterstützt.

Melden von Fehlern

Um Fehler in Vorlagenanalysen zu melden, übermittle ein Direct Support-Ticket mit den folgenden Angaben:

• Fragethema: WABiz: Cloud API
• Anfrage-Typ: Bug oder Implementierungsproblem

Vorlagenanalysen bestätigen

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
}

Vorlagenanalyseparameter

Beispiele

Alle Vorlagenanalysen abrufen

Szenario: Abrufen aller Kennzahltypen der Vorlagenanalyse für eine Authentifizierungsvorlage und eine Marketingvorlage mit einem URL-Button in einem Zeitraum von einem Tag.

Beispielanfrage:

curl -g 'https://graph.facebook.com/v21.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...'

Beispielantwort:

{
  "data": [
    {
      "granularity": "DAILY",
      "product_type": "cloud_api", // Only available to businesses in the 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": "quick_reply_button",
              "button_content": "Contact Support",
              "count": 108
            },
            {
              "type": "unique_url_button",
              "button_content": "Tell me more",
              "count": 16
            }
          ],
          "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"
    }
  }
}

Kosten- und Klick-Metriken

Kostenmetriken werden als Array von Kostenobjekten zurückgegeben, jedes mit einem Typ und einem Wert. Mögliche Typen:

• amount_spent: Gesamtbetrag, der für Unterhaltungen ausgegeben wurde, die innerhalb des start- und end-Zeitraums durch das Senden der Vorlage geöffnet wurden. Siehe Unterhaltungen öffnen.
• cost_per_delivered: amount_spent-Wert geteilt durch die Anzahl der Zustellungen der Vorlage innerhalb des Zeitraums zwischen start und end.
• cost_per_url_button_click: amount_spent-Wert geteilt durch die Anzahl der Klicks auf den URL-Button der Vorlage innerhalb des Zeitraums zwischen start und end. Klicks auf den Schnellantwort-Button werden nicht berücksichtigt. Objekt wird weggelassen, wenn die Vorlage keinen URL-Button hat.

Klick-Metriken werden als Array von JSON-Objekten zurückgegeben, jedes mit einem Typ und einem Wert. Klicks werden nur für URL-Buttons und Schnellantwort-Buttons in Vorlagen zurückgegeben, die als MARKETING oder UTILITY kategorisiert wurden.

Mögliche Typen:

• url_button: Die Gesamtzahl der Klicks auf den URL-Button.
• unique_url_button: Individuelle Klicks verfolgen die Anzahl der verschiedenen WhatsApp-Konten, die auf einen Button geklickt haben. Diese Metrik hilft dir zu verstehen, wie viele einzelne Nutzer*innen mit deinen CTAs interagieren, während gleichzeitig doppelte Klicks von denselben Empfänger*innen eliminiert werden und so eine genaue Messung der Interaktion möglich wird.

Button-Klick-Analysen deaktivieren

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.

Anfragesyntax

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

Anfrageparameter

Beispielanfrage

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

Beispielantwort

Bei Erfolg antwortet die API mit Folgendem:

{
    "success": true
}

Referenz

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.