WhatsApp

WhatsApp messaging runs through the same channel layer as Wave’s other messaging surfaces. You send a message, get a queued acknowledgement immediately, and the real outcome (delivered, read, failed) arrives later as a webhook event.

Sending (text, template, and media) is live — messages reach real phones. Delivery-status and inbound-message webhooks (message.delivered, message.read, message.received) are being finalized on the provider side; until then, sent messages may continue to show as queued in the dashboard even after they’ve actually delivered.

Sending a message

POST /v1/messages

Field	Required	Description
`channel`	✅	`whatsapp` (also accepts `sms`, `webchat`, `email` — those channels aren’t live yet).
`to`	✅	Recipient’s WhatsApp number in E.164 (`+9665XXXXXXXX`).
`content`	✅	One of the three content kinds below.
`conversation_id`	—	Groups related messages into one thread. Defaults to a new thread per message.
`metadata`	—	Key/value object, echoed back on webhooks.

Returns 202 with message_id, provider_message_id, and status: "queued".

Content kinds

Text — a plain message. Only allowed within a 24-hour window of the customer’s last message; outside it, use a template.

{ "channel": "whatsapp", "to": "+9665XXXXXXXX", "content": { "kind": "text", "body": "Your order has shipped!" } }

Template — a pre-approved message for contacting a customer outside the 24-hour window (see Templates below).

{
  "channel": "whatsapp",
  "to": "+9665XXXXXXXX",
  "content": { "kind": "template", "name": "order_update", "language": "en", "variables": { "1": "12345" } }
}

Media — an image, document, audio, or video file.

{
  "channel": "whatsapp",
  "to": "+9665XXXXXXXX",
  "content": {
    "kind": "media",
    "mediaType": "image",
    "url": "https://your-cdn.example/receipt.png",
    "contentType": "image/png",
    "sizeBytes": 84213,
    "filename": "receipt.png"
  }
}

contentType and sizeBytes are required for media to actually send — Wave’s WhatsApp provider needs both known upfront and can’t derive them from the URL alone. Fetch the file’s headers yourself (a HEAD request) if your own system doesn’t already know them.

Templates

Templates are reviewed and approved before they can be used to start a conversation with a customer. GET /v1/messages/templates — list your templates and their approval status (pending / approved / rejected). POST /v1/messages/templates — submit a new template.

Field	Required	Description
`name`	✅	Unique template name.
`language`	✅	Language code the template was written in (`en`, `ar`, …).
`category`	✅	`UTILITY`, `MARKETING`, or `AUTHENTICATION` — this affects both approval rules and pricing.
`body`	Required for `UTILITY`/`MARKETING`	Template text. Use `{{1}}`, `{{2}}`, … for variables. Ignored for `AUTHENTICATION` — see below.
`variables`	—	Sample values for each variable, used during approval review. Not used for `AUTHENTICATION`.
`header`	—	Plain-text header line. Ignored for `AUTHENTICATION`. A media (image/video/document) header isn’t supported yet.
`footer`	—	Plain-text footer line. Ignored for `AUTHENTICATION`.
`buttons`	—	Up to 3 buttons — see Buttons below. Ignored for `AUTHENTICATION` (use `otpButton` instead).
`otpButton`	—	`AUTHENTICATION` templates only — adds a one-tap “copy code” button.

An AUTHENTICATION template has no custom body at all — Meta owns the verification-code wording, so body/variables/header/footer/buttons are all ignored for this category. The otpButton adds a one-tap “copy code” button with no label to configure (Meta generates it).

Buttons

Each entry in buttons is one of three types:

{ "type": "QUICK_REPLY", "text": "Track order" }
{ "type": "URL", "text": "View details", "url": "https://your-site.example/orders/1" }
{ "type": "PHONE_NUMBER", "text": "Call us", "phoneNumber": "+9665XXXXXXXX" }

Viewing, editing, and deleting a template

GET /v1/messages/templates/:name?language=en — full detail for one template (body, header, footer, buttons) — the language query parameter is required since the same name can exist in more than one language. PUT /v1/messages/templates/:name?language=en — update an existing template. Takes the same body as create; editing a template resubmits it for approval, so its status returns to pending. DELETE /v1/messages/templates/:name?language=en — permanently remove a template.

Delivery-status events

Subscribe to these via webhooks the same way as call events. message.sent is listed for completeness but is not delivered to your webhook endpoint — it’s Wave’s internal billing event, generated the moment a send is accepted.

Event	Meaning	Delivered to your webhook?
`message.sent`	Accepted for delivery.	No — internal billing event only.
`message.received`	A customer replied to you.	Yes
`message.delivered`	The message reached the customer’s device.	Yes
`message.read`	The customer opened it.	Yes
`message.failed`	Delivery failed — check the event’s `reason` field.	Yes

queued ──▶ sent ──▶ delivered ──▶ read
                 └─▶ failed

Message log

Every inbound and outbound WhatsApp message is recorded. View them on the Messages page in the dashboard, or fetch them with GET /v1/messages (cursor-paginated, same shape as call logs).

Get Started

Voice

Web Callback

Reference

WhatsApp

Sending a message

Content kinds

Templates

Buttons

Viewing, editing, and deleting a template

Delivery-status events

Message log

​Sending a message

​Content kinds

​Templates

​Buttons

​Viewing, editing, and deleting a template

​Delivery-status events

​Message log

Sending a message

Content kinds

Templates

Buttons

Viewing, editing, and deleting a template

Delivery-status events

Message log