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.
- 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 parameter | Required | Description |
|---|---|---|
country | Yes | The destination country for the estimate, for example BR. |
lookbackWindow | Yes | The 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.
1curl -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": 100011},12{13"bidAmount": 3125,14"estimatedCost": { "lower": 2356.8175590276, "upper": 3113.5824409724 },15"estimatedDeliveries": { "lower": 125, "upper": 325 },16"targetedUsers": 100017},18{19"bidAmount": 12500,20"estimatedCost": { "lower": 3403.3, "upper": 4481.3 },21"estimatedDeliveries": { "lower": 669, "upper": 867 },22"targetedUsers": 100023}24],25"lookbackWindow": "L7D"26}
| Property | Description |
|---|---|
country | The country for which the estimate is calculated. |
currency | The currency of the monetary amounts in the response. |
lookbackWindow | The look-back window used to generate the estimate. |
disclaimer | Reminder that the data is informational only. |
estimates | A list of estimates, one for each bid amount. |
estimates[].bidAmount | The bid amount (in the smallest unit of the WABA currency) that the estimate applies to. |
estimates[].estimatedCost | The estimated cost as lower and upper bounds. |
estimates[].estimatedDeliveries | The estimated number of deliveries as lower and upper bounds. |
estimates[].targetedUsers | The 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. |
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_amountmatches your current fixed rate, your costs stay the same or decrease. - If
bid_amountis 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 type | Value |
|---|---|
| Requests | 20 per hour, per Twilio account |
| Burst | Up 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.