Last updated:
A developer in Gurgaon wires up an order-confirmation message for a client’s online store. The API call returns a clean success response. The customer never gets the message, and nobody can tell why for two days.
A WhatsApp API send message request fails quietly for one of three reasons: a template that wasn’t approved, a customer window that had closed, or a token that expired. This guide walks through your first WhatsApp API send message call in the order things actually go wrong, so you can fix each one before it costs you a day.
Key Takeaways
- A WhatsApp API send message request is one authenticated
POSTto/<PHONE_NUMBER_ID>/messageson Meta’s Graph API. You need a phone number ID, an access token, a recipient who has opted in, and either an open 24-hour window or an approved template. - A free-text WhatsApp API send message only works inside the 24-hour customer service window. Outside it, only a pre-approved template message goes through.
- The temporary token on Meta’s setup screen is for testing only. For anything live, create a system user and generate a permanent token.
- A “success” response means Meta accepted your request. It does not mean the message was delivered, so you need the delivery status webhooks.
- A new business portfolio can message 250 unique customers in 24 hours outside the service window, and Meta charges per delivered message.
What Do You Need Before a WhatsApp API Send Message Request Works?
You need a Meta developer account, a business app with the WhatsApp product added, a phone number connected to a messaging account, an access token, and a recipient who has agreed to hear from you. The code itself is the short part. Most first attempts at a WhatsApp API send message call stall on setup.
Meta’s getting-started steps run in this order: register as a developer, create an app in the App Dashboard with the “Connect with customers through WhatsApp” use case, pick or create a business portfolio, then connect a messaging account under API Setup. Meta gives you a test phone number there, and you should save both the test phone number ID and the messaging account ID. You’ll paste them into every request.
One rule sits outside the technical steps. You may only message users who have opted in. That means a customer who gave their number to you and agreed to WhatsApp messages, not a number copied from a list.
How Do You Get a WhatsApp API Access Token?
You generate one in two places depending on the stage. For your first test, click “Generate access token” in API Setup. For anything live, create a system user in Business Settings and generate a permanent token.
The temporary token is fine for a first WhatsApp API send message test, but Meta says it “expires quickly” and isn’t suitable for development. Treat it as a throwaway for the first test. If you see error code 190, “Your access token has expired”, that’s usually why.
For the permanent token, the steps are:
- In Business Settings, create a system user.
- Assign your app (Manage app) and your WhatsApp account (Manage WhatsApp Business accounts) with full control.
- Generate a token with three permissions:
business_management,whatsapp_business_messagingandwhatsapp_business_management. - Store it like a password, in an environment variable or a secrets manager, never in the page source or a public repository.
How Do You Send a Text Message With the WhatsApp API?
You send a POST request to https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages with a JSON body and an Authorization: Bearer header. Meta’s own example in its send messages guide uses version v26.0 and sends Content-Type: application/json.
Here is the shape of a text message in a WhatsApp API send message call, with placeholders for your own values:
curl -X POST "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<CUSTOMER_NUMBER_WITH_COUNTRY_CODE>",
"type": "text",
"text": {
"preview_url": true,
"body": "Hi Anita, your order is packed and leaves today."
}
}'preview_url tells WhatsApp to show a link preview if your text contains a link. If your token has access to more than one messaging account on the number, Meta also asks you to include messaging_account_id. Otherwise leave it out.
A text like this only lands if the customer has messaged you in the last 24 hours. That is the rule that trips up almost every first WhatsApp API send message attempt, so it gets its own section next.
What Is the 24-Hour Customer Service Window?
It is the period after a customer messages or calls you during which you can send free-form messages. A new message or call from the customer resets the timer to 24 hours. Once the window closes, you can only send pre-approved template messages.
This is why a test often works for you and fails for a real customer. When you test, you reply to Meta’s sample message, which opens a window. Replying to the test message opens a 24-hour customer service window, so your text goes through. A customer who last wrote to you three days ago has no open window, and the same WhatsApp API send message request fails.
If you see error 131047, the explanation is literal: more than 24 hours have passed since the recipient last replied. The fix is a template.
How Do You Send a Template Message?
You send the same WhatsApp API send message request with type set to template and a template object that names an approved template, its language code, and values for its placeholders. Templates are the only message type you can send outside a customer service window, so every reminder, broadcast and “your order shipped” message that goes to a cold conversation uses one.
Every template has a name, a category and a language code. The category must be marketing, utility or authentication, and the category also decides what Meta charges. Templates are reviewed automatically when you create or edit them. An approved one carries the status APPROVED; anything else cannot be sent. In WhatsApp Manager the “In Review” state can last up to 24 hours, so create templates a day before you need them.
A template send looks like this:
curl -X POST "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<CUSTOMER_NUMBER_WITH_COUNTRY_CODE>",
"type": "template",
"template": {
"name": "order_shipped",
"language": { "code": "en" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Anita" },
{ "type": "text", "text": "ORD-20417" }
]
}
]
}
}'Values go into the placeholders in order for positional parameters, or by parameter_name for named ones. Send exactly one value per placeholder. A mismatch returns error 132000, where the number of variable parameters didn’t match the template. For your very first test, Meta’s setup screen sends its pre-made hello_world template with the temporary token, so you don’t have to wait for an approval.
How Do You Know the Message Was Delivered?
You don’t from the response alone. A successful response returns messages[0].id, the WhatsApp message ID, and only means the API accepted the request, not that the message was delivered. Every WhatsApp API send message integration needs a second half that listens for the result.
Delivery news arrives through the messages webhook, which sends status updates for sent, delivered, read and failed. Subscribe to it, store the message ID from your send response, and match the statuses to it. Meta’s guidance is that if no delivered status arrives before the message’s time-to-live ends, you should assume it was dropped. The default time-to-live is 30 days, and 10 minutes for authentication templates, which is why an OTP that arrives late is often an OTP that never arrives.
Meta also notes that messages aren’t guaranteed to arrive in the order you sent them. If message two only makes sense after message one, wait for the delivered status before sending it.
Why Did My WhatsApp API Send Message Request Fail?
Most failures map to a handful of error codes, and each one points to a specific fix. Here are the ones you’re likely to meet first, using the wording in Meta’s error code reference:
| Code | What Meta says | What to do |
|---|---|---|
| 190 | Your access token has expired | Generate a new token, and move to a permanent system-user token |
| 131047 | More than 24 hours have passed since the recipient last replied | Send an approved template instead of free text |
| 132001 | The template doesn’t exist in the specified language, or hasn’t been approved | Check the template name, language code and approval status |
| 132000 | The number of variable values doesn’t match the template | Send one value for each placeholder |
| 131026 | Unable to deliver message | The number may not be on WhatsApp, may not have accepted the latest terms, or may run an old app version |
| 130429 | Cloud API message throughput has been reached | Wait and retry, or slow your sending rate |
| 131056 | Too many messages from your number to the same recipient in a short period | Wait before messaging that person again |
What Are the Sending Limits and Costs?
A new business portfolio starts at 250 unique customers per rolling 24 hours for messages sent outside the service window. To reach 2,000, you complete any one of three paths: verify your business, have your partner verify it, or deliver 2,000 messages to unique numbers inside 30 days using high-quality templates. Beyond that, Meta raises the limit a level at a time when your message quality is high and you’ve used at least half your current limit in the last seven days. Limits are set at the portfolio level, so one number can use up capacity that your other numbers share.
Cost is per delivered message, so every WhatsApp API send message that lands has a price. Since 1 July 2025 Meta charges per message, based on the category and the recipient’s country, and only when the message is delivered. Two things changed on 1 October 2026: service messages beyond the 1,000 free per month per phone number are now charged, and utility messages sent inside an open window are charged too. Any guide that still says “replies are free” has gone stale. Meta’s pricing page doesn’t print the India rupee rates in its body, so get the current figures from Meta’s rate card before you promise a client a per-message number. India billing also moves to INR, and accounts have to migrate by 31 December 2026.
A Worked Example: A Dental Clinic’s Appointment Reminder
Say a dental clinic in South Delhi wants to run a WhatsApp API send message flow for appointment reminders. The numbers below are illustrative, not a client result.
The clinic’s front desk has 600 patients who have ticked a WhatsApp consent box on the registration form. Reminders go out the evening before the visit, which almost always falls outside any 24-hour window, so each one needs a utility template such as “Hi {{1}}, your appointment is tomorrow at {{2}}.” The template is created and approved a day ahead. With 600 patients and perhaps 30 visits a day, the clinic stays far below the 250-unique-customers-a-day starting limit.
When a patient replies “Can I move this to Friday?”, the window opens and the clinic can answer in plain text for the next 24 hours, with no template needed. If the clinic’s developer only tests the reminder with their own phone, which has an open window from the setup message, they will never see error 131047. They will see it on the first real send. That’s why you test your WhatsApp API send message flow with a number that hasn’t messaged you recently.
Should You Build This Yourself?
If you have a developer and a simple use case such as order or appointment messages, yes, and the steps above are enough to get a first WhatsApp API send message out. If you need a shared inbox, broadcasts to thousands of people, chatbots or CRM sync, you’re better off with a platform built on the same API than writing all of it from scratch. Our guide to WhatsApp marketing software covers what to look for before you pay, and our guide to WhatsApp marketing messages covers what to say once the plumbing works.
Either way, the number, the templates and the contact consent should belong to your business, not to whoever built the integration. Ask for that in writing.
FAQ
How do I send a WhatsApp API send message request?
Send a POST request to https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages with an Authorization: Bearer access token and a JSON body that sets messaging_product to whatsapp, the recipient number in to, and either a text or a template message. Inside a 24-hour window you can send text; outside it you must send an approved template.
Can a WhatsApp API send message work without a template?
Yes, but only inside the 24-hour customer service window, which opens when the customer messages or calls you and resets with each new message from them. After it closes, only approved template messages can be sent.
How do I get the phone number ID and access token?
Both appear in API Setup in the App Dashboard once you’ve added the WhatsApp product and connected a messaging account. The temporary token expires quickly, so for live use create a system user in Business Settings and generate a permanent token with the business_management, whatsapp_business_messaging and whatsapp_business_management permissions.
Why does my WhatsApp API send message return success when the customer got nothing?
A success response only means Meta accepted the request. Delivery is reported separately through the messages webhook, which sends sent, delivered, read and failed statuses. Match them to the message ID returned in your send response.
How many WhatsApp API send message calls can I make per day?
A new business portfolio can message 250 unique customers in a rolling 24 hours outside the service window. Completing business verification, or delivering 2,000 messages to unique numbers in 30 days with high-quality templates, raises it to 2,000, and Meta scales it further automatically based on quality and usage.
Stuck on Setup, or Need This Running for Your Business?
If you’d rather not debug a WhatsApp API send message call, tokens and templates yourself, Leyscale’s WhatsApp marketing service sets up the official API and handles template approval with Meta, for businesses that have an opt-in contact list. Our tiers are on the packages page. Tell us what you want to send, to how many people, and from which system, and we’ll say plainly what it takes. Get in touch.
About the Author
