Skip to contentSkip to navigationSkip to topbar
Page tools
Useful for sharing or LLM
Accelerate development with AI

On this pageProducts used
Looking for more inspiration?Visit the

Message Cost Estimate resource


The Message Cost Estimate API returns Meta reach estimates for a specified destination country. Use these estimates to understand how expected deliveries and costs vary at different bid_amount values before you launch a WhatsApp campaign that uses Max Price.

Estimates are based on historical data and are informational only. Meta doesn't publish the underlying algorithm, and the actual delivery volume and cost can differ for each send because of audience size, message volume, and recipient behavior.


Prerequisites

prerequisites page anchor
  • Onboard your account to Max Price and accept the Terms of Service for the Marketing Messages API.
  • Your WhatsApp Business Account (WABA) currency must be supported for Max Pricing.

Request an estimate for a country and a look-back window. The estimate is independent of a specific template, so you don't need to request one estimate per template.

Query parameters

query-parameters page anchor
Query parameterRequiredDescription
countryYesThe destination country for the estimate, for example BR.
lookbackWindowYesThe historical window Meta uses to compute the estimate. Valid values: L1D, L7D, L14D, or L28D. The example that follows uses L7D.

You can't pass bid_amount in this request. The response includes estimates for several bid amounts so you can choose one and set it when you create your MARKETING content template.

Request

request page anchor
1
curl -G "https://messaging.twilio.com/v3/MessageCostEstimate" \
2
-u "$TWILIO_API_KEY:$TWILIO_API_SECRET" \
3
-H "Content-Type: application/json" \
4
--data-urlencode "country=BR" \
5
--data-urlencode "lookbackWindow=L7D"
1
{
2
"country": "BR",
3
"currency": "USD",
4
"disclaimer": "Estimates are based on historical data and are informational only; actual delivery and cost may vary.",
5
"estimates": [
6
{
7
"bidAmount": 2500,
8
"estimatedCost": { "lower": 0, "upper": 0 },
9
"estimatedDeliveries": { "lower": 0, "upper": 0 },
10
"targetedUsers": 1000
11
},
12
{
13
"bidAmount": 3125,
14
"estimatedCost": { "lower": 2356.8175590276, "upper": 3113.5824409724 },
15
"estimatedDeliveries": { "lower": 125, "upper": 325 },
16
"targetedUsers": 1000
17
},
18
{
19
"bidAmount": 12500,
20
"estimatedCost": { "lower": 3403.3, "upper": 4481.3 },
21
"estimatedDeliveries": { "lower": 669, "upper": 867 },
22
"targetedUsers": 1000
23
}
24
],
25
"lookbackWindow": "L7D"
26
}
PropertyDescription
countryThe country for which the estimate is calculated.
currencyThe currency of the monetary amounts in the response.
lookbackWindowThe look-back window used to generate the estimate.
disclaimerReminder that the data is informational only.
estimatesA list of estimates, one for each bid amount.
estimates[].bidAmountThe bid amount (in the smallest unit of the WABA currency) that the estimate applies to.
estimates[].estimatedCostThe estimated cost as lower and upper bounds.
estimates[].estimatedDeliveriesThe estimated number of deliveries as lower and upper bounds.
estimates[].targetedUsersThe number of targeted users the estimate is based on. This figure is a sampling size, not a limit on the number of messages you can send.

Use the estimate to choose a bid amount

use-the-estimate-to-choose-a-bid-amount page anchor

bid_amount is the maximum price per 1,000 message deliveries, expressed in the smallest unit of your WABA currency (for example, cents, centavos, or pence). The factor of 1,000 is part of Meta's pricing formula and isn't a limit on how many messages you can send.

  • If bid_amount matches your current fixed rate, your costs stay the same or decrease.
  • If bid_amount is higher than the fixed rate, the average cost per message can increase, but you might reach a larger audience and see fewer failed deliveries.
  • If you don't set bid_amount, Twilio applies standard fixed rate cards and Max Price doesn't apply.

The Message Cost Estimate API has a dedicated rate limit to protect other WhatsApp operations on your account, such as template creation and phone number onboarding.

Limit typeValue
Requests20 per hour, per Twilio account
BurstUp to 20 requests

If you exceed the limit, Twilio returns HTTP status 429 Too Many Requests. Wait before you retry, and use exponential backoff in automated clients.

Meta's estimates typically change only a few times per day, so polling is unnecessary. Request an estimate while planning your campaign, cache the result, and reuse it as needed.

This limit applies only to the Message Cost Estimate API. It is separate from Twilio's general REST API concurrency limits and from message-sending throughput limits.