Send a WhatsApp message
POST/v1/communication/whatsapp/message
For regular WhatsApp sends, content.text is delivered as a caption with imageUrl, videoUrl or documentUrl. audioUrl has no caption, including with voice=true; send its description as a separate text message. Set from to the sandbox keyword or application-channel UUID to send through the application's WhatsApp Sandbox. to is the external identifier of an active sandbox session. The API key must belong to the application that owns the channel. WhatsApp Sandbox accepts text, the fake sandbox template, image, video, audio and document content. Sandbox errors include SANDBOX_NOT_FOUND, INVALID_SANDBOX_FROM, SANDBOX_APPLICATION_MISMATCH, SANDBOX_SESSION_NOT_FOUND, SANDBOX_SESSION_NOT_CONNECTED, SANDBOX_SESSION_EXPIRED, SANDBOX_CHANNEL_NOT_CONFIGURED, SANDBOX_MESSAGE_LIMIT_REACHED, SANDBOX_TEMPLATE_PARAMETERS_INVALID, SANDBOX_CHANNEL_NOT_ALLOWED, SANDBOX_MESSAGE_SEND_FAILED, and UNSUPPORTED_MESSAGE_TYPE. For a regular channel, an outbound message other than typing or mark-as-read transfers the recipient's active AI session before provider delivery. Non-template content requires a customer inbound message on the same channel within the preceding 24 hours; an active internal session alone does not open that window. Template content may be sent without a recent inbound message when content contains only template and optional context; optional fields omitted from the request do not affect this exemption. enqueued acknowledges provider acceptance, not delivery. From 2026-10-01 at 00:00 America/Sao_Paulo, non-template outbound Service messages include 1,000 free messages per connected number from the first to the last day of each calendar month in the connected number's configured billing time zone (UTC when no WABA time zone has been stored). Reconnecting, renewing the number subscription or resetting organization tiers does not replenish this allowance. Each additional Service message costs BRL 0.09, with no terminal volume cap. Only events from this activation onwards consume that allowance. Insufficient eligible balance rejects the send with the existing 402 insufficient-balance response before provider delivery. Sandbox and template category pricing are unchanged. Sandbox media accepts text, mimeType, filename and voice companions. Sandbox responses are enqueued. Sandbox delivery statuses are scoped to the current sandbox connection. After disconnect/reconnect, late statuses for the previous connection are not delivered to the new connection webhooks. Public message sends may transfer active/awaiting_human sessions and authorize session billing; typing/read controls do not persist messages. HTTP validation/authorization/wallet errors use ApiErrorResponse; HTTP 200 status:error is a provider submission failure. WhatsApp provider authentication, including UT/UAT renewal on migrated connections, is managed by the Hub. API clients continue using their Application x-api-key; provider token changes do not change channel identifiers, message payloads or webhook bindings.
Request
Responses
- 200
- 400
- 401
- 402
- 404
WhatsApp ordinary/sandbox submission returns enqueued, not delivery confirmation. Typing returns messageId:"" with sent; markSeen returns the target ID with sent, or an empty ID with status:error when no target exists.
Invalid payload, including WHATSAPP_TEMPLATE_CATEGORY_INVALID when the persisted template has no billable category, or WHATSAPP_CUSTOMER_WINDOW_CLOSED when non-template content lacks a customer inbound message from the preceding 24 hours.
Invalid API key
Insufficient wallet balance; message submission or session billing was not authorized.
Application channel not found or does not match the API key