WhatsApp Business Platform > Business Management API > Guides

Analytics

You can use the analytics and conversation_analytics fields to get metrics about messages and conversations associated with your WhatsApp Business Account (WABA). Specifically, you can get the number of messages sent and delivered as well as conversation and cost information for a given period.

Getting The Data

Once you know what data you need to get, start to assemble the URL you will call. Your URL needs to include the following parts:

Graph API URL: https://graph.facebook.com/
Graph API Version: v17.0/
Your WABA ID
Analytics option selection: ?fields=analytics or ?fields=conversation_analytics
Filtering options: time range (required), granularity (required), and any other optional filters.
Access Token: See Access Tokens.

By the end, the URL you call looks like this:

https://graph.facebook.com/v17.0/{whatsapp-business-account-ID}
  ?fields=analytics
  .{filtering-parameters}
  &{access-token}

Or like this:

https://graph.facebook.com/v17.0/{whatsapp-business-account-ID}
  ?fields=conversation_analytics
  .{filtering-parameters}
  &{access-token}

Filtering options are different for ?fields=analytics and ?fields=conversation_analytics requests. See more information below.

To find the ID of a WhatsApp Business Account, go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the account you want to use and click on it. A panel opens, with information about the account, including the ID.

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:

Name Description (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/v17.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.

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:

Name	Description (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	`COST`: Includes approximate charges for that time range, in the WABA’s currency. `CONVERSATION`: Includes the count of conversations for that time range.
`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/v17.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/v17.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/v17.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/v17.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/v17.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"
}

Reference

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

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API