Send a text message
POST/api/sessions/:sessionId/messages/send-text
Send a text message
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 413
- 422
- 501
- 503
Message sent
Session not active or invalid request
The API key is missing, unknown, revoked, or expired
The API key's role, session or chat scope, or IP allow-list does not allow this operation
The quotedMessageId could not be resolved: the whatsapp-web.js page does not hold it, or the Baileys store does not (it was never received or sent by this session, or it was evicted or deleted). On whatsapp-web.js a message that resolves but cannot be replied to is sent without the quote.
The session is not connected: an engine exists for it but is not ready, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for ready and retry. A send whose first attempt had already run when the session left ready (or WhatsApp Web reloaded its page) is the exception: it answers a 409 with no code that says the message may or may not have been sent, so check the chat before sending it again (a retry with the same Idempotency-Key answers IDEMPOTENCY_OUTCOME_UNKNOWN). A session that was never started answers 400 instead, and the session lifecycle routes answer 409 for a conflicting state rather than this. One window answers this while the session still reads ready: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and until it has the answer is a 409 naming the reload, with code ENGINE_PAGE_RELOADING and retryAfterSeconds. That takes seconds on most reloads and can take a few minutes, and no event marks its end: ask again at that interval.
The customLinkPreview image, as decoded thumbnailBase64 or as downloaded from thumbnailUrl, exceeds 5 MiB (or MEDIA_DOWNLOAD_MAX_BYTES, if that is lower).
IDEMPOTENCY_KEY_REUSED: the Idempotency-Key was already used with a different route or body.
A caller-supplied customLinkPreview is not supported by the whatsapp-web.js engine — only Baileys can attach one. The send itself is supported on both; omit the field, or use linkPreview. whatsapp-web.js also refuses a send with quotedMessageId to a channel (<id>@newsletter) or a status or broadcast list (@broadcast); nothing is sent.
The session routes its URL fetches through an egress proxy, and the customLinkPreview.thumbnailUrl fetch failed or timed out before any response arrived, so nothing was sent. The proxy or the target behind it may be at fault; the gateway cannot tell which. Without a session proxy the same failure answers 400. Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its Idempotency-Key), times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its Idempotency-Key taken), or the connection closes before the message is written (nothing was sent, and a keyed send frees its Idempotency-Key).