Sending messages
Text, documents, images, video, audio, location, contacts, polls, reactions.
Sending is asynchronous. A successful call means the message was accepted for sending (native 202, status QUEUED; Green-style 200 with an idMessage). Follow it through QUEUED, PROCESSING, SENT, DELIVERED, READ (or FAILED / CANCELLED) with GET /instances/{id}/messages/{id}, webhooks or the polling queue. A success response never means delivered.
Common fieldsLive
| Field | Notes |
|---|---|
| chatId | WhatsApp: a phone number (2348012345678 or +234 801 234 5678), a Green-style id (2348012345678@c.us), a group id (1203630...@g.us) or a LID (...@lid). Telegram and MAX: the numeric chat id (see Channels) |
| Idempotency-Key | Header, up to 128 characters. The same key on the same instance never sends twice |
| externalRef | Native only. Your own reference, e.g. an invoice number. Stored, filterable and returned in webhooks |
| quotedMessageId | Optional: reply to (quote) an earlier message |
TextLive
{
"chatId": "2348012345678",
"text": "Hello from Sendjade",
"externalRef": "INV-1042"
}Documents and media (PDF invoices)Live, phone check
The recipient gets a real WhatsApp attachment with a filename and caption, not a link. Send a URL we can fetch, or upload the bytes. Files are limited to 25 MB (PDF, Office files, images, video, audio). URLs are fetched server-side with SSRF protection (http/https only, public addresses only, redirects re-checked), file types are verified by their content, and executables are rejected.
{
"chatId": "2348012345678",
"url": "https://files.example.com/inv-1042.pdf",
"fileName": "Invoice-1042.pdf",
"caption": "Your invoice is attached. Due Friday.",
"externalRef": "INV-1042"
}Other message typesLive, phone check
| Native endpoint (POST, Member) | Body (besides chatId) | Green-style method |
|---|---|---|
| /instances/{id}/messages/location | latitude, longitude, name?, address? | sendLocation (nameLocation) |
| /instances/{id}/messages/contact | contact: { phoneNumber, firstName, lastName?, company? } | sendContact (phoneContact) |
| /instances/{id}/messages/poll | question, options[2..12], multipleAnswers? | sendPoll |
| /instances/{id}/messages/reaction | messageId, emoji | sendReaction (reaction) |
| /instances/{id}/messages/forward | messageId (text and received media only) | forwardMessages |
| PATCH /instances/{id}/messages/{messageId} | text (edit) | editMessage |
| DELETE /instances/{id}/messages/{messageId} | delete for everyone | deleteMessage |
| /instances/{id}/chats/typing | state: composing, recording or paused | sendTyping |
| /instances/{id}/chats/read | messageIds? | readChat |
ResponseLive
{
"data": {
"message": { "id": "9f2c...", "waMessageId": "3EB0A1B2C3D4E5F6A7", "status": "QUEUED", "externalRef": "INV-1042" },
"duplicate": false
}
}The waMessageId is assigned when the message is queued and never changes, so it is the same id you will see in later status webhooks.
Safety limitsLive
- Sends to a number that opted out are refused with
422 recipient_opted_out. Customers who reply STOP, UNSUBSCRIBE, CANCEL or OPT OUT are added automatically. - Each number has a rolling 24-hour cap (default 500, configurable per instance) and a pace of 30 sends per 10 seconds. See Rate limits.
- Sending needs a connected instance: otherwise
409 instance_not_connected.