Send a WhatsApp Message with an API: cURL Guide
Sending a WhatsApp message through an API is one HTTP request. You say who it goes to and what it says, and you get back a message ID. This guide shows the request for text, replies, images and documents, the recipient format that trips most people up, and the errors you can run into. It works from any language that can make an HTTP call; if you want one in your own language, we have guides for Python, Node.js and PHP.
What you need
- An API key. You find it in your dashboard under Settings, API Key. Keep it on your server and out of public code.
- An instance ID. An instance is one connected WhatsApp number. Pair it by scanning a QR code once, and copy its ID from the instance page.
- A recipient. The next section explains the format.
There is no Meta Business verification and no template approval, because the instance is a regular WhatsApp account. The free trial lasts 14 days with no credit card, and the quickstart walks through pairing.
The recipient: one format for people and groups
The to field is the recipient's WhatsApp ID. For a person you can pass the plain international number, with the country code and no spaces, such as 1234567890, and the API turns it into the full ID for you. You can also send the full form yourself, the number followed by @s.whatsapp.net. A group needs its full ID, which ends in @g.us. The examples below use the full form for a person.
Send a text message
Every request carries the same two headers: X-Api-Key and X-Instance-Id.
curl -X POST https://api.wsapi.chat/messages/text \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-api-key" \
-H "X-Instance-Id: your-instance-id" \
-d '{"to": "1234567890@s.whatsapp.net", "text": "Hello from WSAPI!"}'A successful call returns 201 and a body like {"id": "01234567890123456"}. Keep that ID: you use it later to reply to, edit or delete the message.
Reply to a message or mention someone
To answer a specific message, add its ID as replyTo and the sender's ID as replyToSenderId. In a group, list the people you mention in mentions and write their number after an @ in the text. The same request accepts isForwarded to mark a message as forwarded and ephemeralExpiration (24h, 7d or 90d) for disappearing messages.
Send an image or a document
Media uses its own endpoint and takes either a public URL or base64 data, not both. A URL can point to a file of up to 50 MB. If you leave out mimeType, it is detected for you.
curl -X POST https://api.wsapi.chat/messages/image \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-api-key" \
-H "X-Instance-Id: your-instance-id" \
-d '{"to": "1234567890@s.whatsapp.net", "url": "https://example.com/cat.jpg", "caption": "Cat pic"}'Documents work the same way at /messages/document, with one extra required field, filename, which is the name the recipient sees:
curl -X POST https://api.wsapi.chat/messages/document \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-api-key" \
-H "X-Instance-Id: your-instance-id" \
-d '{"to": "1234567890@s.whatsapp.net", "url": "https://example.com/report.pdf", "filename": "report.pdf", "caption": "Monthly report"}'Video, audio, voice notes, stickers, locations and contact cards follow the same pattern, each with its own endpoint in the API reference.
When a request fails
| Status | What it means | What to do |
|---|---|---|
| 201 | The message was accepted and you have its ID | Store the ID |
| 400 | The body is invalid, for example a missing to or text | Read the detail field |
| 401 | The key or the instance ID is wrong | Check both headers |
| 409 | The instance is not paired | Scan the QR code again |
| 503 | The instance is not available right now | Retry after a moment |
| 504 | WhatsApp did not answer in time | Retry the request |
Errors come back as JSON with a status and a detail, so your code can log the reason instead of guessing.
Try it without a phone
Run any of the requests above exactly as written and you will get 401 with Invalid Instance ID. That is the right answer to placeholder credentials, and it proves the endpoint is reachable and your headers are read. Replace the placeholders with your own and the same request sends a message.
For messages with tappable choices instead of plain text, see buttons and lists, which use the same headers and a similar body.
FAQ
Do I need a WhatsApp Business API account to send messages?
No. The instance connects a regular WhatsApp account, so there is no Meta Business verification and no template approval.
What does a successful response look like?
A 201 with the new message ID in an id field.
Can WhatsApp restrict my number?
WSAPI connects a regular WhatsApp account, so WhatsApp's usage policies apply and accounts that send unsolicited bulk messages can be limited.