Message Limit

---

Authorization

Add this header to every request in this page

{
  "Authorization": "Bearer ${token}"
}

🔒 Message Limit

This endpoint returns your account's message sending allowances and balance in a single response. The response contains three different types of information:

Topic	What does it describe?	Related section
Service message allowance	The number of replies you can send for free after a customer messages you	Service message
Message template allowance	The monthly template sending allowance included in your package	Message template
Credit	The balance you have loaded to your account for paid messages	Credit

The request does not require a body or any parameters. Being authenticated is sufficient.

GET

https://backend.helorobo.com/agent-app/message-limit

Response

{
  "trace_id": "<trace_id>",
  "data": {
    "monthly_conversation_limit": 2003,
    "limit_type": "COUNT",
    "monthly_credit_limit": 0,
    "free_service_message_limit": 15,
    "free_service_message_usage": 30,
    "free_service_message_channels": [
      {
        "channel_id": "<channel_id>",
        "name": "Mağaza Hattı",
        "phone_number": "905551112233",
        "waba_id": "<waba_id_1>",
        "usage": 9
      },
      {
        "channel_id": "<channel_id>",
        "name": "Destek Hattı",
        "phone_number": "905554445566",
        "waba_id": "<waba_id_2>",
        "usage": 4
      },
      {
        "channel_id": "<channel_id>",
        "name": "Satış Hattı",
        "phone_number": "905557778899",
        "waba_id": "<waba_id_2>",
        "usage": 17
      }
    ],
    "package_price": 4999,
    "package_currency": "TRY",
    "message_count": 13,
    "free_message_count": 0,
    "total_cost": 17.621594995278564,
    "country_conversation_limits": [
      {
        "country": "TR",
        "limit": 2000,
        "message_count": 13,
        "remaining_conversation": 1987
      },
      {
        "country": "CA",
        "limit": 1,
        "message_count": 0,
        "remaining_conversation": 1
      }
    ],
    "billtekrom": {
      "total_payment_cost": 100,
      "currency_code": "USD"
    }
  }
}

Fields

Field	Type	Description
limit_type	string	Indicates how your template allowance is tracked. COUNT means it is tracked by number of messages, CREDIT means it is tracked by amount.
monthly_conversation_limit	number	Your total monthly template sending allowance (count). Used when limit_type is COUNT.
monthly_credit_limit	number	Your total monthly template sending allowance (amount). Used when limit_type is CREDIT.
message_count	number	The number of template messages you have sent this month.
total_cost	number	The total cost of paid messages sent this month. The value is returned unrounded.
country_conversation_limits	array	If your package includes country-based allowances, the allowance and usage for each country.
free_service_message_limit	number	The monthly free service message allowance of a single phone number.
free_service_message_usage	number	The total number of service messages sent by all your numbers this month.
free_service_message_channels	array	Service message usage for each phone number.
package_price	number	The price of your package.
package_currency	string	The currency of the package price.
billtekrom / shopify	object	Your credit balance information. Depending on where your account is billed, only one of these two objects is returned. Their fields are the same.

Service message

What is a service message?

When a customer messages you on WhatsApp, you can reply to them with free-form text, without using a template, for 24 hours from that moment. Replies you send within this 24-hour window are called service messages.

Campaign, order notification, and verification messages do not count as service messages. These are template messages and are deducted from your allowance described in the Message template section.

How is the allowance distributed?

The free service message allowance is not given to your account as a whole, but to each phone number separately. You can think of it as a quota belonging to a single number:

• free_service_message_limit is the quota of a single number. If your account has three numbers, each of them has its own quota.
• Even if different numbers are under the same WABA (WhatsApp Business Account), their quotas are separate from each other.
• Unused allowance of one number is not transferred to another number. When a number's quota runs out, messages sent from that number become paid, even if other numbers still have allowance left.

What happens when the allowance runs out?

When a number's allowance runs out, service messages sent from that number are charged and the amount is deducted from your WhatsApp credit.

If free_service_message_limit is 0, your account has no free service message allowance; all service messages are charged from your credit.

Message template

What is a message template?

Message templates are ready-made messages pre-approved by Meta. When you want to message a customer outside the 24-hour window, you need to use a template. Campaign announcements, order notifications, and verification codes fall into this group.

Depending on your package, your template allowance is tracked in one of two ways. You can tell which one applies from the limit_type field.

Tracking by count (COUNT)

If limit_type is COUNT, your package gives you a specific number of template sends per month.

	Field	Example
Total allowance	monthly_conversation_limit	2003
Usage	message_count	13
Remaining	Total allowance − usage	1990

If usage exceeds the total allowance, the difference gives the overage count. There is no overage in the example account.

Country-based allowances

In some packages, the template allowance is split by country. For example, one allowance may be defined for sending to numbers in Türkiye and a separate one for sending to numbers in Canada. If your package has such a split, each country's allowance is returned separately in the country_conversation_limits list. The country field is a two-letter country code.

	Field	Türkiye (TR)	Canada (CA)
Total allowance	limit	2000	1
Usage	message_count	13	0
Remaining	remaining_conversation	1987	1

The remaining allowance per country is returned ready in the response (remaining_conversation), so you don't need to calculate it yourself.

Tracking by amount (CREDIT)

If limit_type is CREDIT, your package grants you a monthly spending amount instead of a message count. The cost of each template send is deducted from this amount.

	Field
Total allowance	monthly_credit_limit
Usage	total_cost
Remaining	Total allowance − usage

In this case, you can still see the number of templates you have sent in the message_count field.

Credit

What is credit?

Credit is the balance you load to your account for paid WhatsApp messages. Messages that exceed your package allowance and service messages sent from numbers whose free allowance has run out are charged from this balance.

Credit information is returned in a different object depending on where your account is billed:

• For accounts billed through Billtekrom, in the billtekrom object,
• For accounts billed through Shopify, in the shopify object.

Both objects have the same fields, and the calculation is done the same way.

Calculating remaining credit

	Field	Example
Loaded credit	total_payment_cost	100 USD
Spent	all_total_cost (or total_cost if this field is missing)	17.62 USD
Remaining	Loaded − spent	82.38 USD

The currency is specified in the currency_code field.

The total_cost value is returned unrounded (17.621594995278564 in the example). We recommend rounding it to two decimal places when displaying it to users.

Package price

The package_price and package_currency fields show the price and currency of the package you are using. The package price in the example is 4999 TRY.