Documentation

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

FieldNotes
chatIdWhatsApp: 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-KeyHeader, up to 128 characters. The same key on the same instance never sends twice
externalRefNative only. Your own reference, e.g. an invoice number. Stored, filterable and returned in webhooks
quotedMessageIdOptional: reply to (quote) an earlier message

TextLive

POST /instances/{id}/messages/text
{
  "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.

POST /instances/{id}/messages/file
{
  "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/locationlatitude, longitude, name?, address?sendLocation (nameLocation)
/instances/{id}/messages/contactcontact: { phoneNumber, firstName, lastName?, company? }sendContact (phoneContact)
/instances/{id}/messages/pollquestion, options[2..12], multipleAnswers?sendPoll
/instances/{id}/messages/reactionmessageId, emojisendReaction (reaction)
/instances/{id}/messages/forwardmessageId (text and received media only)forwardMessages
PATCH /instances/{id}/messages/{messageId}text (edit)editMessage
DELETE /instances/{id}/messages/{messageId}delete for everyonedeleteMessage
/instances/{id}/chats/typingstate: composing, recording or pausedsendTyping
/instances/{id}/chats/readmessageIds?readChat

ResponseLive

202 Accepted (native)
{
  "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.