Checking usage and statistics

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

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 Hub

Clients and Partners can see a specific WABA usage in the Insights 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 is 1 request per 10s.

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

Name

Type

Description

client_id*

string

ID of the client

partner_id*

string

ID of the partner

Query Parameters

Name Type Description

Name	Type	Description
from_month	number	Show usage starting from specified month. Example: `>=1` `<=12This will be deprecated by October 1st,2023.`
from_year	number	Show usage starting from specified year. Example: `2020This will be deprecated by October 1st,2023.`
end_date	UNIX Timestamp	Supported from October 1st, 2023. 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	Supported from October 1st, 2023. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: 1672531200
granularity	string	Supported from October 1st, 2023. 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.

from_month

number

Show usage starting from specified month. Example: >=1 <=12This will be deprecated by October 1st,2023.

from_year

number

Show usage starting from specified year. Example: 2020This will be deprecated by October 1st,2023.

end_date

UNIX Timestamp

Supported from October 1st, 2023.

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

Supported from October 1st, 2023. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date.

Example: 1672531200

granularity

string

Supported from October 1st, 2023.

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.

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

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

Name

Type

Description

partner_id*

string

client_id*

string

channel_id*

string

Query Parameters

Name Type Description

Name	Type	Description
start_date	string	Supported from October 1st, 2023. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: `1672531200`
end_date	string	Supported from October 1st, 2023. The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date. Example: `1672531200`
granularity	string	Supported from October 1st, 2023. 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.
from_year		Describes from which year we need to fetch the history. `This will be deprecated by October 1st,2023.`
from_month	String	Describes from which month we need to fetch the history `This will be deprecated by October 1st,2023.`
app_ids		To get usage accumulated from selected app_ids (e.g. `?app_ids=100,200)`

start_date

string

Supported from October 1st, 2023. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date.

Example: 1672531200

end_date

string

Supported from October 1st, 2023.

The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date.

Example: 1672531200

granularity

string

Supported from October 1st, 2023.

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.

from_year

Describes from which year we need to fetch the history. This will be deprecated by October 1st,2023.

from_month

String

Describes from which month we need to fetch the history

This will be deprecated by October 1st,2023.

app_ids

To get usage accumulated from selected app_ids (e.g. ?app_ids=100,200)

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

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`

<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

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.

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.

PreviousPartner Permission to Generate API Key NextMigrating phone numbers

Last updated 2 months ago