WhatsApp Business Management API

Analytics

You can use the analytics and conversation_analytics fields to get metrics about messages and conversations associated with your WhatsApp Business Account (WABA). For example, you can get the number of messages sent and delivered, conversation and cost data, and the number of times each of its templates have been sent.

Only metrics for business phone numbers and templates associated with your WABA at the time of the request will be included in the response.

Getting The Data

Use the WhatsApp Business Account endpoint to get analytics.

Query Syntax

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

Query String Parameters

PlaceholderDescriptionExample Value

<FIELDS>

Required.


Metric. Value can be one of:


analytics

<FILTERING_PARAMATERS>

Required.


Metric filtering parameter. Append additional filtering parameters using dots.


For possible values, see:


.start(1543543200).end(1544148000).granularity(DAY)

Analytics

The analytics field provides the number and type of messages sent and delivered by the phone numbers associated with a specific WABA — for conversation metrics, see Conversation Analytics. When calling /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}, you can attach the following parameters.

Analytics Parameters

NameDescription (Click the arrow in the left column for supported options.)

start

type: UNIX Timestamp

Required.

The start date for the date range you are retrieving analytics for.

end

type: UNIX Timestamp

Required.

The end date for the date range you are retrieving analytics for.

granularity

type: String

Required.

The granularity by which you would like to retrieve the analytics.

Supported Options

  • HALF_HOUR
  • DAY
  • MONTH

phone_numbers

type: Array

Optional.

An array of phone numbers for which you would like to retrieve analytics. If not provided, all phone numbers added to your WABA are included.

product_types

type: Array

Optional.

The types of messages (notification messages and/or customer support messages) for which you want to retrieve notifications. Provide an array and include 0 for notification messages, and 2 for customer support messages. If not provided, analytics will be returned for all messages together.

country_codes

type: Array

Optional.

The countries for which you would like to retrieve analytics. Provide an array with 2 letter country codes for the countries you would like to include. If not provided, analytics will be returned for all countries you have communicated with.

Example

Scenario: You need to get the number of messages sent and delivered by all phone numbers associated with your WABA.

Suggested Solution: Assemble the URL you want to call and include the following filtering parameters: start, end, granularity. Then, make a GET request to that URL:

curl -i -X GET \ 
"https://graph.facebook.com/v18.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

A successful response returns an analytics object with the data you have requested:

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

Conversation Analytics

Conversation-based pricing has changed. See Pricing to learn how our new conversation-based pricing model works.

In addition, visibility of metric_types have changed effective July 1, 2023. Please see the Conversation Analytics table for more details.

The conversation_analytics field provides cost and conversation information for a specific WABA. When calling /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}, you can attach the following parameters.

Conversation Analytics Parameters

NameDescription (Click the arrow in the left column for supported options.)

start

type: UNIX Timestamp

Required.

The start date for the date range you are retrieving analytics for.

end

type: UNIX Timestamp

Required.

The end date for the date range you are retrieving analytics for.

granularity

type: String

Required.

The granularity by which you would like to retrieve the analytics.

Supported Options

  • HALF_HOUR
  • DAILY
  • MONTHLY

phone_numbers

type: Array

Optional.

An array of phone numbers for which you would like to retrieve analytics. If not provided, all phone numbers added to your WABA are included.

metric_types

Optional.

List of metrics you would like to receive. If you send an empty list, we return results for all metric types.

Supported Options {#supported}

  • COST: Includes approximate charges for that time range, in the WABA’s currency.
  • CONVERSATION: Includes the count of conversations for that time range.

As of July 1, 2023, COST is no longer shown for businesses who bill through a Solution Partner. To understand your charges, please reach out to your partner. If you bill through a partner, this is the behavior to expect:

  1. If no metric_types are specified in your request, only CONVERSATION is returned
  2. If only CONVERSATION is specified, only CONVERSATION is returned
  3. If only COST is specified, the following exception is returned:
    • Title: “Cost not available”
    • Message: “Cost is no longer shown for businesses who bill through a partner (i.e., BSP). To understand your charges, please reach out to your partner.”

If you query a time period that includes dates on or after July 1, 2023, (e.g., May 1, 2023 through August 1, 2023), the response will include the exception above.

There is no change for partners when querying the conversation_analytics endpoint.

conversation_categories

Optional.

List of conversation categories. If you send an empty list, we return results for all conversation categories.

Supported Options

  • AUTHENTICATION
  • MARKETING
  • SERVICE
  • UTILITY

conversation_types

Optional.

List of conversation types. If you send an empty list, we return results for all conversation types.

Supported Options

  • FREE_ENTRY: Conversations originating from a free entry point.
  • FREE_TIER: Conversations within the monthly free tier.
  • REGULAR: Any conversations that did not originate from a free entry point or are above the monthly free tier allotment.

conversation_directions

Optional.

List of conversation directions. If you send an empty list, we return results for all conversation directions.

Supported Options

  • BUSINESS_INITIATED: Conversations initiated by the business.
  • USER_INITIATED: Conversations initiated by an end user/customer.

dimensions

Optional.

List of breakdowns you would like to apply to your metrics. If you send an empty list, we return results without any breakdowns.

Supported Options

  • CONVERSATION_CATEGORY
  • CONVERSATION_DIRECTION
  • CONVERSATION_TYPE
  • COUNTRY
  • PHONE

Analytics data is approximate and may differ from what’s shown on invoices due to small variations in data processing.

Examples

Given a time range, you can get conversation and cost information associated with your WABA. If you want, you can filter and break down your results. See the code samples below for examples.

Getting Monthly Data, Using All Breakdowns

Scenario: Given a month, you want to retrieve all conversation and cost information for all phone numbers associated with a WABA.

Suggested Solution: Assemble the URL you want to call and include the following filtering parameters:

  • start: Start of your time range. In this case, the beginning of the month you want metrics for.
  • end: End of your time range. In this case, the end of the month you want metrics for.
  • granularity: How granular you want your data points to be. In the example below, we use MONTHLY, so each datapoint will represent a month’s worth of data.
  • phone_numbers: Send an empty array and we return information for all phone numbers associated with the WABA.
  • dimensions: Set it to all available breakdowns: "CONVERSATION_CATEGORY", "CONVERSATION_TYPE", "COUNTRY", and "PHONE".

In this case, you do not need to specify country_codes, metric_types, conversation_types and conversation_categories. If you don't send us anything for those fields, we return all available options. Once you set up the URL, make a GET request:

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

A successful response returns a conversation_analytics object with the data you have requested. In the following example, the WABA contains only one phone number.

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

Getting Data for a Specific Phone Number, Using All Breakdowns and Half Hour Granularity

Scenario: Given a time range, you want to retrieve all conversation and cost information for a specific phone number associated with a WABA. In the results, you want to use all possible breakdowns. You need each data point to represent half an hour’s worth of data.

Suggested Solution: Assemble the URL you want to call and include the following filtering parameters:

  • start: Start of your time range.
  • end: End of your time range.
  • granularity: How granular you want your data points to be. In the example below, we use HALF_HOUR, so each datapoint represents half an hour’s worth of data.
  • phone_numbers: The phone number you need information for.
  • dimensions: Set it to all available breakdowns: CONVERSATION_CATEGORY, CONVERSATION_TYPE, COUNTRY, and PHONE.

In this case, you do not need to specify country_codes, metric_types, conversation_types, or conversation_categories. If you don’t send us anything for those fields, we return all available options. Once you set up the URL, make a GET request:

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

A successful response returns a conversation_analytics object with the data you have requested:

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

Getting Monthly Data, Using Conversation Type Breakdowns

Scenario: Given a time range, you want to retrieve all conversation and cost information for all phone numbers associated with a WABA. In the results, you want to break down by conversation type.

Suggested Solution: Assemble the URL you want to call and include the following filtering parameters:

  • start: Start of your time range.
  • end: End of your time range.
  • granularity: How granular you want your data points to be. In the example below, we use MONTHLY, so each datapoint represents half a month’s worth of data.
  • phone_numbers: Send an empty array and we’ll return information for all phone numbers associated with the WABA.
  • dimensions: Set it to CONVERSATION_TYPE.

In this case, you do not need to specify country_codes, metric_types, conversation_types, conversation_directions, or conversation_categories. If you don't send us anything for those fields, we return all available options. Once you set up the URL, make a GET request:

curl -i -X GET
"https://graph.facebook.com/v18.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

A successful response returns a conversation_analytics object with the data you have requested:

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

Getting Half-Hour Data Broken Down by Conversation Category


Request:

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

Response:

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

#### Getting Half-Hour Data Broken Down by Conversation Type and Conversation Category


Request:

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

Response:

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

Template Analytics (Beta)

Template analytics are in beta but available to everyone. The template_analytics field provides the number of message templates sent, delivered, and read, as well as the number of times a marketing message template button was clicked. Button clicks data are currently available for URL buttons and Quick Reply buttons.

The data for template analytics could also be found on WhatsApp Manager > Message templates > Template details > Insights. Similar to the data presented on WhatsApp Manager, the template_analytics data returned are presented with a daily granularity in the UTC timezone, and you could retrieve template analytics for any time period within the past 90 days.

Limitations

  • Template Analytics are only available for business phone numbers registered for use with Cloud API. Analytics are not collected for template messages sent using a number registered for use with the On-Premises API.
  • WhatsApp Business Accounts that are owned by or shared with Meta business accounts in the European Union (EU), United Kingdom (UK), and Japan, or that have a business phone number with a country calling code from countries or regions in the EU, UK, or Japan, are ineligible for template analytics.

Reporting Bugs

To report template analytics bugs, submit a Direct Support ticket with the following selections:

  • Question Topic: WABiz: Cloud API
  • Request Type: Template Analytics API

Confirming Template Analytics

You must confirm template analytics on your WhatsApp Business Account before you can get template analytics. You can confirm template analytics using the WhatsApp Manager or the API. To confirm via API, send the following request:

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

Once confirmed, we will begin capturing template analytics for the WhatsApp Business Account. Once confirmed, template analytics cannot be disabled.

Upon success, the API will respond with your WhatsApp Business Account ID. For example:

{                          
  "id": 102290129340398
}

Template Analytics Parameters

NameDescriptionExample Value

start

UNIX Timestamp

Required.


The start timestamp for the date range you are retrieving analytics for. As template analytics are being provided with a daily granularity in the UTC timezone, a start timestamp other than 0:00 UTC would be corrected to its prior 0:00 UTC.

1543536000

end

UNIX Timestamp

Required.


The end date for the date range you are retrieving analytics for. As template analytics are being provided with a daily granularity in the UTC timezone, an end timestamp other than 0:00 UTC would be corrected to its next 0:00 UTC.

1543708800

granularity

Enum

Required.


The granularity by which you would like to retrieve the analytics. Supported values:


  • DAILY

DAILY

template_ids

Array of IDs

Required.


An array of template IDs for which you would like to retrieve analytics for.


Maximum 10.

[1924084211297547,954638012257287,969725530748535]

metric_types

Array of enums

Optional.


The types of metrics which you want to retrieve. If omitted or an empty array, analytics for all metric types will be returned.


Possible values:


  • CLICKED
  • DELIVERED
  • READ
  • SENT

["SENT","DELIVERED","READ"]

Examples

Given a time range, you can get the following template-level insights associated with your WABA:

  • The number of times a message template was sent, delivered, and read. These metrics are available for any template type.
  • The number of times a button on a message template was clicked on. Button clicks data are currently available for URL buttons and Quick Reply buttons. Click data is currently only available for marketing message templates.

Getting all template analytics

Scenario: Given a 2-day period, get all available template analytics for a single message template associated with a WhatsApp Business Account.

Example Request:

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

Example Response:

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

Reference

For a list of all possible values for each field, refer to the Graph API reference of the WhatsApp Business Account Analytics field.