Insights

Free Service Messages

Estimated usage of Meta's 1,000 free service messages per WhatsApp number for a calendar month (UTC).

GET /api/v1/public/insights/free-tier

warning

Pricing since 1 October 2026: each WhatsApp number gets 1,000 free service messages (non-template messages inside the 24-hour window) per calendar month. After that, Meta charges every service message at the utility rate. Unused free messages don't carry over to the next month.

How It's Counted

This is an estimate from the messages sent through this platform, not Meta billing data. Your Meta invoice is the final number.

Counted: non-template messages you sent, by the time they were created (UTC).

Not counted:

• Template messages.
• Failed messages.
• Messages sent from the WhatsApp Business app (coexistence).
• History sync messages.
• Messages sent within 7 days after the customer messaged you from a Click-to-WhatsApp ad. See Click-to-WhatsApp Ads.

Query Parameters

Parameter	Type	Required	Description
month	string	no	Month in YYYY-MM format (UTC). Defaults to the current month.
phone_number_id	string	no	Limit to one number: the phone number's id or Meta phone_number_id from List Phone Numbers. Defaults to all numbers.

Example Request

cURL

curl -X GET "https://chat.api.co.id/api/v1/public/insights/free-tier?month=2026-10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://chat.api.co.id/api/v1/public/insights/free-tier?month=2026-10",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data } = await response.json();
for (const number of data.phone_numbers) {
  console.log(number.display_phone_number, number.used, "/", number.limit);
}

Python

response = requests.get(
    "https://chat.api.co.id/api/v1/public/insights/free-tier",
    params={"month": "2026-10"},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

for number in response.json()["data"]["phone_numbers"]:
    print(number["display_phone_number"], number["used"], "/", number["limit"])

Response

{
  "success": true,
  "data": {
    "month": "2026-10",
    "is_estimate": true,
    "phone_numbers": [
      {
        "id": "clxxx1234567890",
        "display_phone_number": "+62 811-2000-1001",
        "limit": 1000,
        "used": 1047,
        "remaining": 0,
        "estimated_billable": 47
      }
    ]
  }
}

Response Fields

Parameter	Type	Required	Description
used	number	yes	Estimated service messages sent this month.
remaining	number	yes	Free service messages left: max(0, limit - used).
estimated_billable	number	yes	Service messages over the free limit that Meta will likely charge: max(0, used - limit).

Click-to-WhatsApp Ads

Leads per Click-to-WhatsApp ad for a calendar month (UTC), plus how many customers are in a free entry point window right now.

GET /api/v1/public/insights/ctwa

info

When a customer messages you from a Click-to-WhatsApp ad, a free entry point window opens for up to 7 days. Every message to that customer is free during it, and those messages don't count toward the 1,000 free service messages. To check a single customer, use Check Messaging Window.

Query Parameters

Parameter	Type	Required	Description
month	string	no	Month in YYYY-MM format (UTC). Defaults to the current month.
phone_number_id	string	no	Limit to one number: the phone number's id or Meta phone_number_id. Defaults to all numbers.

Example Request

cURL

curl -X GET "https://chat.api.co.id/api/v1/public/insights/ctwa?month=2026-10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://chat.api.co.id/api/v1/public/insights/ctwa?month=2026-10",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data } = await response.json();
console.log("Customers in a free ad window:", data.active_free_windows);

Python

response = requests.get(
    "https://chat.api.co.id/api/v1/public/insights/ctwa",
    params={"month": "2026-10"},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

for ad in response.json()["data"]["ads"]:
    print(ad["headline"], ad["leads"])

Response

{
  "success": true,
  "data": {
    "month": "2026-10",
    "active_free_windows": 24,
    "ads": [
      {
        "ad_id": "120210000000001",
        "headline": "Flash Sale 10.10",
        "source_url": "https://fb.me/abc123",
        "source_type": "ad",
        "leads": 11,
        "chats": 14,
        "last_lead_at": "2026-10-09T08:12:00.000Z"
      }
    ]
  }
}

Response Fields

Parameter	Type	Required	Description
active_free_windows	number	yes	Customers whose free entry point window is open right now (not limited to the month).
ad_id	string	yes	Meta ad ID (referral.source_id from the webhook).
headline	string | null	yes	Ad creative headline sent by Meta. This is not the ad name from Ads Manager.
leads	number	yes	Unique customers who messaged you from this ad in the month.
chats	number	yes	Inbound messages from this ad in the month (one customer can start several).

Try it out

tip

Press Try it and paste your API key (kc_live_...) into the API key (Bearer) field. Get the key from API Keys. Requests run against your live account, so endpoints that send, create, or delete act on real data.

• GET/api/v1/public/insights/free-tierFree Service Messages
• GET/api/v1/public/insights/ctwaClick-to-WhatsApp Ads