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.

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