API reference

Messages

Send WhatsApp messages and read their delivery status.

The one rule of WhatsApp messaging

WhatsApp only allows free-form text inside a 24-hour window that opens when a customer messages you. Outside that window — and for anyone who has never messaged you, like OTP recipients — you must send a pre-approved template. Business-initiated messages (OTP, cart, order updates) are always template sends.

Send a message

POST/messages

Requires the messages:send scope. Unknown phone numbers are created as contacts automatically.

Body parameters

Field	Type	Description
`to`req	`string`	Recipient in E.164 format, e.g. +15551234567.
`type`req	`"text" \| "template"`	Which kind of message to send.
`text`	`string`	The message text. Required when type is "text". Max 4096 chars.
`template`	`object`	Template payload. Required when type is "template".
`template.name`	`string`	Approved template name (see GET /templates).
`template.language`	`string`	BCP-47 code, e.g. en_US. Only needed if the name exists in multiple languages.
`template.variables`	`string[]`	Values for {{1}}, {{2}}, … in order.
`contactName`	`string`	Names the contact if it is created on the fly.

Template send (OTP, alerts, updates)

curl -X POST "$MYWA_API/messages" \
  -H "Authorization: Bearer $MYWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "type": "template",
    "template": { "name": "otp_code", "variables": ["483920"] },
    "contactName": "Jane Doe"
  }'

The mywa helper above is the small client from Libraries.

Free-form text (inside the 24h window)

bash

curl -X POST "$MYWA_API/messages" \
  -H "Authorization: Bearer $MYWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "type": "text", "text": "Thanks! Your order has shipped 🎉" }'

If the window is closed you get 409 window_closed. Fall back to a template send.

Response

json

{
  "id": "msg_9f2a…",
  "conversationId": "cnv_1a2b…",
  "contactId": "cts_3c4d…",
  "to": "+15551234567",
  "type": "template",
  "status": "sent",
  "body": "Your verification code is 483920",
  "createdAt": "2026-07-18T09:30:00.000Z"
}

Get message status

GET/messages/:id

Requires messages:read. Poll this to track delivery.

bash

curl "$MYWA_API/messages/msg_9f2a…" -H "Authorization: Bearer $MYWA_KEY"

json

{
  "id": "msg_9f2a…",
  "conversationId": "cnv_1a2b…",
  "direction": "out",
  "status": "delivered",
  "errorCode": null,
  "body": "Your verification code is 483920",
  "createdAt": "2026-07-18T09:30:00.000Z"
}

status progresses queued → sent → delivered → read, or becomes failed (then errorCode carries Meta’s reason).