Checking usage and statistics

Businesses using the WhatsApp Business Platform are being charged per conversation until 2025, which includes all messages delivered in a 24-hour session with a particular WhatsApp user. See Conversations documentation.

Through the Monthly usage data, you get to see the number of conversations the phone number had and when; it includes All, Free, and Paid Conversations.

This information is an estimate and can slightly differ from invoices. It can be checked in the 360dialog Hub (by Partners and Clients), via Partner API (by Partners only, which can be used to create personalized dashboards for their clients) and via Webhook notifications (which requires development of an additional counter).

Please note that final information about charges in only available in the invoices sent after the month has ended.

In the 360dialog Hub

Clients and Partners can see a specific WABA usage in the Funds dashboard. To access it, click in Show details in the specific WABA you wish to use and select Insights on the top menu.

Through the Monthly usage graphs, you get to see the number of conversations the phone number had and when; it includes All, Free, and Paid Conversations.

Here, you can also estimate costs for the future through the Approximate charges graph, which shows the estimation of the costs of charges.

If the client is registered under Direct Payment, you will also be able to see their balance settings in this same page.

Please be aware that the Approximate Charges displayed in the 360dialog Hub is financially binding in its totality. The precise amount due will be determined by Meta's invoice at the end of the month, which will serve as the authoritative record of charges.

In the Partner API

If your clients are registered with direct payment, you can use the check balance endpoint to get usage information.

Please see how to use this here.

Granularity

You can use the granularity parameter to retrieve metrics about the conversations associated with the 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. This parameter works together with the /balance endpoint in the Partner API. See below how to parse your request.

Get balance of Client Hub

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/clients/{client_id}/info/balance

Rate limit: 5 requests per 30 seconds.

Request example

curl --request GET --url https://hub.360dialog.io/api/v2/partners/{partner_id}/clients/{client_id}/info/balance?start_date=1664582400&end_date=1667260799&granularity=day --header 'Authorization: ' --header 'Content-Type: application/json'

Path Parameters

Name	Type	Description
client_id*	string	ID of the client
partner_id*	string	ID of the partner

Query Parameters

Name	Type	Description
end_date	UNIX Timestamp	The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date. Example: 1672531200
start_date	UNIX Timestamp	The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: 1672531200
granularity	string	The granularity by which you would like to retrieve the analytics. Supported Options: DAY , MONTH Defaults with MONTH if no value is provided in the request.

200: OK

The balance field is only relevant for clients who are registered with direct payment.

usage: The response contains an array called "usage" that provides a breakdown of the channel's usage in different categories. These categories may include authentication, marketing, service, utility. Each category within the array includes details such as paid quantity, price, and quantity. This allows you to analyze the usage patterns and associated costs for different aspects of the channel's messaging services.

{
        "balance": 50.00,
        "currency": "eur",
        "last_renewal": {
          "date": "2023-08-01T00:00:00Z,
          "amount": 20.00
        },
        "bi_price_for_currency_and_client_country": 0.2,
        "ui_price_for_currency_and_client_country": 0.02,
        "estimated_template_cost": 0.03,
        "granularity": "day",
        "usage": [
          {
            "authentication_paid_quantity": 0,
            "authentication_price": 0.0,
            "authentication_quantity": 0,
            "marketing_paid_quantity": 0,
            "marketing_price": 0.0,
            "marketing_quantity": 0,
            "service_paid_quantity": 0,
            "service_price": 0.0,
            "service_quantity": 0,
            "utility_paid_quantity": 0,
            "utility_price": 0.0,
            "utility_quantity": 0,
            "business_initiated_paid_quantity": 5,
            "business_initiated_price": 1.0,
            "business_initiated_quantity": 5,
            "free_entry_point": 0,
            "free_quantity": 0,
            "free_tier": 0,
            "paid_quantity": 5,
            "period_date": "2023-08-10T00:00:00Z",
            "quantity": 5,
            "total_price": 1.0,
            "user_initiated_paid_quantity": 0,
            "user_initiated_price": 0.00,
            "user_initiated_quantity": 0
          },
          {
            "authentication_paid_quantity": 0,
            "authentication_price": 0.0,
            "authentication_quantity": 0,
            "marketing_paid_quantity": 0,
            "marketing_price": 0.0,
            "marketing_quantity": 0,
            "service_paid_quantity": 0,
            "service_price": 0.0,
            "service_quantity": 0,
            "utility_paid_quantity": 0,
            "utility_price": 0.0,
            "utility_quantity": 0,
            "business_initiated_paid_quantity": 0,
            "business_initiated_price": 0,
            "business_initiated_quantity": 0,
            "free_entry_point": 0,
            "free_quantity": 0,
            "free_tier": 0,
            "paid_quantity": 5,
            "period_date": "2023-08-11T00:00:00Z",
            "quantity": 5,
            "total_price": 0.05,
            "user_initiated_paid_quantity": 5,
            "user_initiated_price": 0.05,
            "user_initiated_quantity": 5
          }
        ]
      }

404: Not Found

{
  "meta": {
    "success": false,
    "http_code": 400,
    "developer_message": "There was an error with your request",
    "details": [
      "string"
    ],
    "error_data": {
      "code": "string",
      "message": "string",
      "real_message": "string",
      "status": 0
    }
  }
}

Get Channel Balance

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/info/balance

Request Example curl --request GET --url https://hub.360dialog.io/api/v2/partners/partner_id/clients/client_id/channels/channel_id/info/balance --header 'Accept: application/json' --header 'Authorization: '

Path Parameters

Name	Type	Description
partner_id*	string
client_id*	string
channel_id*	string

Query Parameters

Name	Type	Description
start_date	string	The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: 1672531200
end_date	string	The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date. Example: 1672531200
granularity	string	The granularity by which you would like to retrieve the analytics. Supported Options: DAY , MONTH Defaults with MONTH if no value is provided in the request.
app_ids		To get usage accumulated from selected app_ids (e.g. ?app_ids=100,200)

200: OK

{
  "balance": 123.5,
  "bi_price_for_currency_and_client_country": 0.01,
  "currency": "EUR",
  "estimated_template_cost": 0.02,
  "last_renewal": {
    "amount": 100.5,
    "date": "2019-08-24T14:15:22Z"
  },
  "ui_price_for_currency_and_client_country": 0.05,
  "usage": [
    {
      "authentication_paid_quantity": 0,
      "authentication_price": 0,
      "authentication_quantity": 0,
      "marketing_paid_quantity": 1300,
      "marketing_price": 13,
      "marketing_quantity": 1800,
      "service_paid_quantity": 500,
      "service_price": 2.5,
      "service_quantity": 1000,
      "utility_paid_quantity": 0,
      "utility_price": 0,
      "utility_quantity": 0,
      "business_initiated_paid_quantity": 0,
      "business_initiated_price": 0,
      "business_initiated_quantity": 0,
      "free_entry_point": 20,
      "free_quantity": 1020,
      "free_tier": 1000,
      "paid_quantity": 1800,
      "period_date": "2023-08-24T14:15:22Z",
      "quantity": 2800,
      "total_price": 12.5,
      "user_initiated_paid_quantity": 0,
      "user_initiated_price": 0,
      "user_initiated_quantity": 0
    }
  ]
}

Query Syntax

GET/info/balance?<FILTERING_PARAMETER>

Example:

https://hub.360dialog.io/api/v2/partners/{partner_id}/clients/{client_id}/info/balance?start_date=1664582400&end_date=1667260799&granularity=day

Query String Parameters

Placeholder	Description	Example Value
<FILTERING_PARAMATERS>	Required. Metric filtering parameter. Append additional filtering parameters using dots. For possible values, see: Filtering Parameters	start_date=1664582400&end_date=1667260799&granularity=day

When calling the GET request, you can attach the following{filtering-parameters}to retrieve the cost and conversation information for a specific WABA.

Filtering Parameters

Name	Description
start_date type: UNIX Timestamp	Required. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: 1672531200
end_date type: UNIX Timestamp	Required. The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date. Example: 1672531200
granularity type: String	Required. The granularity by which you would like to retrieve the analytics. Supported Options: DAY MONTH Defaults with MONTH if no value is provided in the request.
app_id type: array	Available only for Get Client Balance endpoint. An array of app_ids for which you would like to retrieve usage. If not provided, all app ids in the WABA are included.

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

Examples

With granularity parameters, you can filter and break down your results. See the code sample below for examples.

GET info/balance?start_date=1691629200&end_date=1691758799&granularity=day

A successful response returns the usage object with the data you have requested.

{
        "balance": 50.00,
        "currency": "eur",
        "last_renewal": {
          "date": "2023-08-01T00:00:00Z,
          "amount": 20.00
        },
        "bi_price_for_currency_and_client_country": 0.2,
        "ui_price_for_currency_and_client_country": 0.02,
        "estimated_template_cost": 0.03,
        "granularity": "day",
        "usage": [
          {
            "authentication_paid_quantity": 0,
            "authentication_price": 0.0,
            "authentication_quantity": 0,
            "marketing_paid_quantity": 0,
            "marketing_price": 0.0,
            "marketing_quantity": 0,
            "service_paid_quantity": 0,
            "service_price": 0.0,
            "service_quantity": 0,
            "utility_paid_quantity": 0,
            "utility_price": 0.0,
            "utility_quantity": 0,
            "business_initiated_paid_quantity": 5,
            "business_initiated_price": 1.0,
            "business_initiated_quantity": 5,
            "free_entry_point": 0,
            "free_quantity": 0,
            "free_tier": 0,
            "paid_quantity": 5,
            "period_date": "2023-08-10T00:00:00Z",
            "quantity": 5,
            "total_price": 1.0,
            "user_initiated_paid_quantity": 0,
            "user_initiated_price": 0.00,
            "user_initiated_quantity": 0
          },
          {
            "authentication_paid_quantity": 0,
            "authentication_price": 0.0,
            "authentication_quantity": 0,
            "marketing_paid_quantity": 0,
            "marketing_price": 0.0,
            "marketing_quantity": 0,
            "service_paid_quantity": 0,
            "service_price": 0.0,
            "service_quantity": 0,
            "utility_paid_quantity": 0,
            "utility_price": 0.0,
            "utility_quantity": 0,
            "business_initiated_paid_quantity": 0,
            "business_initiated_price": 0,
            "business_initiated_quantity": 0,
            "free_entry_point": 0,
            "free_quantity": 0,
            "free_tier": 0,
            "paid_quantity": 5,
            "period_date": "2023-08-11T00:00:00Z",
            "quantity": 5,
            "total_price": 0.05,
            "user_initiated_paid_quantity": 5,
            "user_initiated_price": 0.05,
            "user_initiated_quantity": 5
          }
        ]
      }

Via Webhook

Every time a message is sent, you can see the conversation information in the webhook. You can build a counter to understand usage and statistics based on this objects.

Please see how this is presented in this specific documentation.