GET/blog/send-whatsapp-message-api-curl—200OK
tutorialapi

Send a WhatsApp Message with an API: cURL Guide

November 12, 2026|4 min read

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.

terminal
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.

terminal
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:

terminal
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

StatusWhat it meansWhat to do
201The message was accepted and you have its IDStore the ID
400The body is invalid, for example a missing to or textRead the detail field
401The key or the instance ID is wrongCheck both headers
409The instance is not pairedScan the QR code again
503The instance is not available right nowRetry after a moment
504WhatsApp did not answer in timeRetry 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.