Statistiques

Ce document explique comment obtenir des analyses de messages, de conversations et de modèles qui fournissent certaines données comme le nombre de messages envoyés à partir d’un numéro de téléphone professionnel, le nombre de conversations et leur coût pour un compte WhatsApp Business (WABA), ou le nombre de fois où un modèle donné a été lu.

Seuls les indicateurs relatifs aux numéros de téléphone professionnels et aux modèles associés à votre compte WhatsApp Business au moment de la requête seront inclus dans les réponses.

Obtention des données

Utilisez le point de terminaison Compte WhatsApp Business pour obtenir les données d’analyse.

Syntaxe de la requête

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

Paramètres de chaîne de requête

Analyses des messages

Le champ analytics fournit le nombre et le type de messages envoyés et distribués par les numéros de téléphone associés à un WABA spécifique (pour les indicateurs de conversation, voir Analyse des conversations). Lorsque vous appelez /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}, vous pouvez inclure les paramètres suivants.

Paramètres d’analyse

Exemple

Scénario : vous devez récupérer le nombre de messages envoyés et distribués pour tous les numéros de téléphone associés à votre WABA.

Solution suggérée :constituez l’URL que vous souhaitez appeler et incluez les paramètres de filtrage suivants : start, end et granularity. Ensuite, envoyez une requête GET à cette 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}"

En cas de réussite, la réponse renvoie un objet analytics contenant les données que vous avez demandées :

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

Analyse des conversations

Le champ conversation_analytics fournit des informations sur les conversations et les coûts pour un WABA spécifique. Lorsque vous appelez /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}, vous pouvez inclure les paramètres suivants.

Paramètres d’analyse des conversations

Exemples

Pour une période donnée, vous pouvez obtenir des informations sur les conversations et les coûts associés à votre WABA. Vous pouvez filtrer et répartir vos résultats si vous le souhaitez. Reportez-vous aux exemples de code ci-dessous.

Obtention de données mensuelles avec toutes les répartitions

Scénario : pour un mois donné, vous souhaitez récupérer les informations relatives à l’ensemble des conversations et des coûts pour tous les numéros de téléphone associés à un WABA.

Solution suggérée :constituez l’URL que vous souhaitez appeler et incluez les paramètres de filtrage suivants :

• start : début de votre période. Dans ce cas, début du mois pour lequel vous souhaitez récupérer des indicateurs.
• end : fin de votre période. Dans ce cas, fin du mois pour lequel vous souhaitez récupérer des indicateurs.
• granularity : granularité souhaitée pour les points de données concernés. Dans l’exemple ci-dessous, nous utilisons MONTHLY, de sorte que chaque point de données représente un mois de données.
• phone_numbers : si vous envoyez un tableau vide, nous renvoyons les informations relatives à tous les numéros de téléphone associés au WABA.
• dimensions : définissez ce paramètre sur toutes les répartitions disponibles : "CONVERSATION_CATEGORY", "CONVERSATION_TYPE", "COUNTRY" et "PHONE".

Dans le cas présent, vous n’avez pas besoin de spécifier country_codes, metric_types, conversation_types ni conversation_categories. Si vous ne nous envoyez aucun de ces champs, nous renvoyons toutes les options disponibles. Une fois que l’URL est constituée, envoyez une requête 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}"

En cas de réussite, la réponse renvoie un objet conversation_analytics contenant les données que vous avez demandées. Dans l’exemple suivant, le WABA ne contient qu’un seul numéro de téléphone.

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

Obtention de données concernant un numéro de téléphone spécifique avec toutes les répartitions et une granularité d’une demi-heure

Scénario : pour une période donnée, vous souhaitez récupérer les informations relatives à l’ensemble des conversations et des coûts pour un numéro de téléphone spécifique associé à un WABA. Dans les résultats, vous souhaitez utiliser toutes les répartitions possibles. Vous souhaitez que chaque point de données représente une demi-heure de données.

Solution suggérée : constituez l’URL que vous souhaitez appeler et incluez les paramètres de filtrage suivants :

• start : début de votre période.
• end : fin de votre période.
• granularity : granularité souhaitée pour les points de données concernés. Dans l’exemple ci-dessous, nous utilisons HALF_HOUR, de sorte que chaque point de données représente une demi-heure de données.
• phone_numbers : numéro de téléphone pour lequel vous demandez des informations.
• dimensions : définissez ce paramètre sur toutes les répartitions disponibles : CONVERSATION_CATEGORY, CONVERSATION_TYPE, COUNTRY et PHONE.

Dans le cas présent, vous n’avez pas besoin de spécifier country_codes, metric_types, conversation_types ni conversation_categories. Si vous ne nous envoyez aucun de ces champs, nous renvoyons toutes les options disponibles. Une fois que l’URL est constituée, envoyez une requête 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"

En cas de réussite, la réponse renvoie un objet conversation_analytics contenant les données que vous avez demandées :

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

Obtention de données mensuelles avec une répartition par type de conversation

Scénario : pour une période donnée, vous souhaitez récupérer les informations relatives à l’ensemble des conversations et des coûts pour tous les numéros de téléphone associés à un WABA. Dans les résultats, vous souhaitez une répartition par type de conversation.

Solution suggérée :constituez l’URL que vous souhaitez appeler et incluez les paramètres de filtrage suivants :

• start : début de votre période.
• end : fin de votre période.
• granularity : granularité souhaitée pour les points de données concernés. Dans l’exemple ci-dessous, nous utilisons MONTHLY, de sorte que chaque point de données représente un mois de données.
• phone_numbers : si vous envoyez un tableau vide, nous renvoyons les informations relatives à tous les numéros de téléphone associés au WABA.
• dimensions : définissez ce paramètre sur CONVERSATION_TYPE.

Dans le cas présent, vous n’avez pas besoin de spécifier country_codes, metric_types, conversation_types, conversation_directions ni conversation_categories. Si vous ne nous envoyez aucun de ces champs, nous renvoyons toutes les options disponibles. Une fois que l’URL est constituée, envoyez une requête 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}"

En cas de réussite, la réponse renvoie un objet conversation_analytics contenant les données que vous avez demandées :

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

Obtention de données par demi-heure avec une répartition par catégorie de conversation

Requête :

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

Réponse :

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

#### Obtention de données par demi-heure avec une répartition par type et catégorie de conversation

Requête :

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

Réponse :

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

Analyses des modèles

L’analyse des modèles indique le nombre de fois qu’un modèle a été envoyé, distribué et lu, et le nombre de clics sur les boutons d’URL ou les boutons de réponse rapide dans le modèle.

Les données sont renvoyées selon une granularité quotidienne dans le fuseau horaire UTC avec une période d’analyse allant jusqu’à 90 jours. Vous pouvez également trouver les analyses des modèles dans Gestionnaire WhatsApp > Modèles de message > Détails du modèle > Statistiques.

Limites

• Pour que les analyses de modèles soient disponibles pour l’API On-Premises, le compte ne doit pas avoir activé les analyses de modèles de l’API Cloud.
• Les analyses de modèles de l’API On-Premises sont soumises aux règles d’agrégation et d’anonymisation, qui exigent un minimum de 1 000 évènements avant que les utilisateur·ices ne puissent voir les données.
• Les analyses des clics sur un bouton ne sont disponibles que pour les modèles de catégorie MARKETING ou UTILITY.
• Les WABA détenus par des comptes business Meta, ou partagés avec ces derniers, dans l’Union européenne, au Royaume-Uni ou au Japon, ou qui sont associés à un numéro de téléphone professionnel avec un indicatif d’un de ces pays, ne sont pas pris en charge.

Signalement des bugs

Pour signaler des bugs avec l’analyse des modèles, contactez l’Assistance directe en sélectionnant les informations suivantes :

• Sujet de la question : WABiz : Cloud API
• Type de requête : Bug ou problème d’implémentation

Confirmation de l’analyse des modèles

Vous devez confirmer l’analyse des modèles dans votre compte WhatsApp Business avant de pouvoir récupérer les données d’analyse des modèles. Cette confirmation peut se faire dans le Gestionnaire WhatsApp ou à l’aide de l’API. Pour confirmer via l’API, envoyez la requête suivante :

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

Une fois l’analyse confirmée, nous commençons à collecter les données d’analyse des modèles pour le compte WhatsApp Business. À ce stade, l’analyse des modèles ne peut plus être désactivée.

En cas de réussite, l’API répond avec l’ID de votre compte WhatsApp Business. Par exemple :

{                          
  "id": 102290129340398
}

Paramètres d’analyse des modèles

Exemples

Récupération de toutes les données d’analyse des modèles

Scénario : pour une période de 2 jours donnée, récupérez toutes les données d’analyse disponibles pour un modèle de message unique associé à un compte WhatsApp Business.

Exemple de requête :

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

Exemple de réponse :

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

Désactiver l’analyse des clics sur un bouton

Pour désactiver le suivi des clics sur un bouton d’un modèle particulier, définissez son champ cta_url_link_tracking_opted_out sur true. Une fois le suivi désactivé, l’API ne renvoie plus la propriété de clic dans l’analyse des modèles ni n’affiche les interactions/clics sur un bouton dans le Gestionnaire WhatsApp lorsqu’elle analyse le modèle.

Syntaxe de la requête

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

Paramètres de la requête

Exemple de requête

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

Exemple de réponse

En cas de réussite, l’API répond avec :

{
    "success": true
}

Référence

Vous trouverez la liste complète des valeurs possibles pour chaque champ dans la référence de l’API Graph concernant le champ d’analyse du compte WhatsApp Business.