WhatsApp Analytics

WhatsApp analytics allow you to retrieve detailed metrics for business phone numbers and templates associated with your WABA. Examples include the number and type of messages sent, the number of times a given template has been read, and the number of times a button in a template has been clicked.

Messaging Analytics

Messaging analytics provide the number and type of messages sent and delivered by the phone numbers associated with a specific WABA.

Example Request

To retrieve messaging analytics, send a

GET
request to the following endpoint, replacing waba_id with the ID of the WhatsApp Business Account you want to retrieve messaging analytics data for:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/messaging-analytics

Data is returned with a half-hourly, daily or monthly granularity in the UTC timezone, with a lookback of up to 90 days. You must include the start, end, and granularity parameters in your request, and there are some optional parameters that you can use to further filter the data:

Name Type Required Notes
start string(timestamp) Yes The start date and time format for the analytics data to be retrieved from, in the format YYYY-MM-DD.
end string(timestamp) Yes The end date and time format for the analytics data to be retrieved to, in the format YYYY-MM-DD.
granularity string Yes The granularity of the analytics data to be retrieved. Supported: HALF_HOUR, DAILY, MONTHLY
phone_number array No Phone numbers for which you would like to retrieve analytics. If empty, all WABA-associated phone numbers are included.
product_types array No An array of the message types to retrieve analytics for. Possible values are 0 for notification messages and/or 2 for customer support messages. If not specified, analytics for all message types will be returned.
country_codes array No Two-letter country codes for the countries for which you would like to retrieve analytics. If not specified, analytics for all countries will be returned.

You can find a full code example in the Retrieve Messaging Analytics code snippet.

Example Response

{
   "id": "345688589250625",
   "granularity": "HALF_HOUR",
   "phone_numbers": [
      "16505550111"
   ],
   "country_codes": [
      "US"
   ],
   "_embedded": {
      "messaging_analytics": [
         {
            "start": "1543543200",
            "end": "1543629600",
            "sent": 100,
            "delivered": 90
         }
      ]
   },
   "paging": {
      "cursors": {
         "before": "MAZDZD",
         "after": "MjQZD"
      },
      "next": "https://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?after=MAZDZD",
      "previous": "https://api.nexmo.com/v2/channel-manager/wabas/106499765517625/messaging-analytics?before=MjQZD"
   }
}

Template Analytics

Template analytics describe the number of times a template has been sent, delivered, and read, and the number of times URL buttons or Quick Reply buttons in the template have been clicked; button click analytics are only available for templates categorized as MARKETING or UTILITY.

Data is returned with a daily granularity in the UTC timezone with a lookback of up to 90 days.

Please note: You must confirm template analytics on your business account before you can retrieve template analytics. See the WhatsApp documentation for more information.

Enabling Template Analytics

Before you can retrieve template analytics for your WhatsApp Business Account (WABA), you must enable insights collection at the WABA level. Insights is analytics data with respect to messages, pricing or templates, including tracking template button or link clicks. This is a one-time configuration step performed per WABA.

Important: Enabling insights directs Meta to collect and anonymize data from your chats with customers. Meta uses this anonymized data to improve WhatsApp services. Once enabled, template analytics cannot be disabled for the entire WABA. Enabling is done once per WABA ID (not per template or phone number).

Enabling insights allows Meta to:

  • Collect anonymized chat data from your WABA
  • Generate template analytics showing delivery, read, and click metrics
  • Provide this data through the Template Analytics API

Enable Insights for Your WABA

Endpoint:

PATCH
/v1/channel-manager/whatsapp/wabas/{waba_id}/enable_insights

Use the same authentication method as other Channel Manager endpoints. The API key must be linked to the WABA ID.

Response Codes:

Code Description
200 Request successful - insights successfully enabled
403 Unauthorized - API key is not linked to this WABA ID
404 Resource not found - WABA ID is invalid

Once insights are enabled, allow a few minutes for the setting to propagate. You can then begin retrieving template analytics data.

Example Request

To retrieve template analytics, send a

GET
request to the following endpoint, replacing waba_id with the ID of the WhatsApp Business Account you want to retrieve template analytics data for:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/template-analytics

The query parameters detailed below can be used to filter the results:

Name Type Required Notes
start string(timestamp) Yes The start date and time format for the analytics data to be retrieved from, in the format YYYY-MM-DD.
end string(timestamp) Yes The end date and time for the analytics data to be retrieved to, in the format YYYY-MM-DD. The maximum difference between the start and end dates is 90 days.
granularity string Yes Must be DAILY.
template_ids array Yes An array of the template_ids of the template(s) to retrieve analytics for. Maximum 10.
metric_types array No An array of the metric types to retrieve analytics for. Possible values are SENT, DELIVERED, READ, and CLICKED. You can read more about what each type means in the WhatsApp documentation. If empty, analytics for all metric types will be returned.

Example Response

{
   "granularity": "DAILY",
   "product_type": "cloud_api",
   "page_size": 100,
   "_embedded": {
      "template_analytics": [
         {
            "template_id": "458951126288942",
            "start": "2024-11-11T00:00:00Z",
            "end": "2024-11-11T00:00:00Z",
            "sent": 100,
            "delivered": 90,
            "read": 80,
            "clicked": 70
         }
      ]
   },
   "_links": {
      "self": {
         "href": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/template-analytics?template_ids=[458951126288937]&start=2024-11-10&end=2024-11-14&page_size=100&cursor=c2VsZj1udWxs"
      }
   }
}

Pricing Analytics

Pricing analytics allow you to retrieve pricing breakdowns and tiering information for any message delivered within a specified date range.

Example Request

To retrieve pricing analytics, send a

GET
request to the following endpoint, replacing waba_id with the ID of the WhatsApp Business Account you want to retrieve template analytics data for:

https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/:waba_id/pricing-analytics

The query parameters detailed below can be used to filter the results:

Name Type Required Notes
start string(timestamp) No The start date and time for the analytics data to be retrieved from, in the format YYYY-MM-DD.
end string(timestamp) No The end date and time for the analytics data to be retrieved to, in the format YYYY-MM-DD.
granularity string No Must be one of HALF_HOUR, DAILY, or MONTHLY.
phone_numbers array No Phone numbers for which you would like to retrieve analytics. If not specified, analytics for all phone numbers associated with the WABA will be returned. Example: [ "16505550111" ]
country_codes array No Two-letter country codes for the countries for which you would like to retrieve analytics. If not specified, analytics for all countries will be returned. Example: [ "US" ]
dimensions array No List of breakdowns you would like to apply to your metrics. If empty, all results returned without any breakdowns. Can include PRICING_CATEGORY, PRICING_TYPE, COUNTRY, PHONE, and TIER.
tier array No The tier property value represents a concatenation of the lower and upper bounds for the tier specific to the market–category pair (country and pricing_category). Example: [ "0:100000" ]

Example Response

{
   "granularity": "DAILY",
   "product_type": "cloud_api",
   "_embedded": {
      "pricing_analytics": [
         {
            "start": "2024-11-11T00:00:00Z",
            "end": "2024-11-11T00:00:00Z",
            "volume": 100,
            "phone_number": "14155552671",
            "country": "US",
            "tier": "75000:150000",
            "pricing_type": "REGULAR",
            "pricing_category": "AUTHENTICATION"
         }
      ]
   },
   "paging": {
      "cursors": {
         "before": "MjQZD",
         "after": "MAZDZD"
      },
      "previous": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MjQZD",
      "next": "https://api.nexmo.com/v1/channel-manager/whatsapp/wabas/345688589250625/pricing-analytics?before=MAZDZD"
   }
}

Further Reading