Skip to main content
POST
Send a WhatsApp message

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Headers

Idempotency-Key
string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

Required string length: 1 - 255
X-Test-Mode
enum<string>

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Available options:
true,
false

Body

application/json
to
string
required

E.164 phone number OR WhatsApp Business Solution UID (5-130 alphanumeric chars).

type
enum<string>
required

Message kind. text and the media kinds (image/document/audio/video/location/contact) are only permitted inside Meta's 24h customer-service window; outside it, use template with an approved template or the send is rejected with 422.

Available options:
text,
template,
image,
document,
audio,
video,
location,
contact,
interactive,
reaction
from
string

Sender E.164 (overrides default WABA number).

Required string length: 1 - 64
text
object

Freeform text body — required when type is text. Only permitted inside Meta's 24h customer-service window.

interactive
object

Interactive payload — required when type is interactive (list / buttons / cta_url / flow / product / product_list).

reaction
object

Reaction payload — required when type is reaction. References an earlier outbound message by Meta id and carries a single emoji.

template
object

Approved template to send — required when type is template. language.code MUST match the locale the template was approved under in WhatsApp Manager (e.g. en_US, en_GB, es_ES, pt_BR), or the send is rejected with 422 WHATSAPP_TEMPLATE_NOT_FOUND (Meta 132001). Supply variables via either components (Meta-native) or the flat template_params sibling field below — not both.

template_params
object

Flat string→string map filling the template's positional {{N}} placeholders (keys '1'..'N'). Alternative to the Meta-native template.components shape.

coupon
object

Optional Limited-Time-Offer coupon config — when supplied, a deterministic per-recipient coupon code is generated and attached to the send's paired COPY_CODE button. Skip this and set metadata.lto_coupon_code directly to supply a literal code instead.

media
object

Media payload — required when type is image, document, audio, or video. url must be a signed HTTPS URL (e.g. one returned by POST /api/v1/files/upload).

webhook_url
string

DLR callback URL (HTTPS). Optional — an empty string is treated as 'no webhook'. Non-empty values are validated server-side: must be https:// and pass the SSRF guard.

Maximum string length: 2048
metadata
object

Arbitrary string→string metadata, echoed back on delivery-status webhooks and message lookups.

scheduled_at
string

ISO 8601 timestamp to schedule delivery instead of sending immediately (e.g. "2026-08-01T15:00:00Z"); a datetime-local value without a timezone suffix is also accepted.

conversation_id
string

Open thread's conversation id — scopes the 24h customer-service window pre-flight to the same inbound match the composer uses. Does not re-thread the outbound message.

Maximum string length: 100
contact_id
string

Resolved contact id for the recipient — scopes the 24h customer-service window pre-flight (parity with the composer's window-status probe).

Maximum string length: 100

Response

Message accepted for delivery (whatsapp)

Message accepted for delivery (whatsapp)

data
object
meta
object