WhatsApp Cloud API
Meta's official WhatsApp Business platform. The 24-hour window, templates, media and delivery status.
kind: "whatsapp_cloud" is a number connected through Meta's official WhatsApp Business
Platform (Cloud API). It is the right choice for anything automated or at volume: it is what
WhatsApp built for businesses, and it is the channel Meta will not ban you for using as intended.
What it can do
| Text | Yes, inside the 24-hour window |
| Templates | Yes, when templates are enabled for your workspace (sendTemplates) |
| Media | Yes, when WhatsApp Cloud media is enabled for your workspace (sendMedia) |
| Interactive (buttons, lists) | When enabled for your workspace (sendInteractive) |
| Quoted replies | When interactive messages and media are enabled for your workspace (quotedReplies) |
| Start a conversation | Yes, with an approved template (startConversations, when templates are enabled). Free text to someone with no conversation answers 422, reason outside_24h_window |
| Campaigns | Yes |
| Delivery | queued (202) when media is enabled for your workspace, else immediate (201) |
Read the connection's capabilities for what is enabled for you; the table is the full feature
set.
Start a conversation
WhatsApp only lets a business message someone first with an approved template. Send one with to
(an E.164 number) or contactId:
curl https://app.gauge.chat/backend/v2/messages \
-H "Authorization: Bearer $GAUGE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "9b2f6c1e-3d4a-4e5b-8f70-1a2b3c4d5e6f",
"to": "+447700900123",
"template": {
"name": "appointment_reminder",
"language": "en_GB",
"variables": { "1": "Layla", "2": "Tuesday 22 October", "3": "10:30" }
}
}'Gauge creates the contact and the conversation if they do not exist yet (or reuses the ones that
do), sends the template, and answers 202 with the conversationId. When the customer replies,
the 24-hour window opens and you can send free text into that conversation. The template must be
approved, in the language you name, with exactly its variables; see
Templates.
The 24-hour window
Free-form messages are allowed only within 24 hours of the customer's last message. Outside it,
a free-text send answers 422 unsupported_channel_action with reason outside_24h_window: send an
approved template instead. Details: The 24-hour window and templates.
Delivery status
A queued send answers 202 with status: queued: Gauge accepted the message and hands it to
WhatsApp right after the request. WhatsApp's progress arrives as
message.status_updated events, each with status one of
sent, delivered, read or failed. A failed event carries error: { "reason": "…" }, the
reason in plain words (for example "This number is not on WhatsApp."); every other status has
error: null. The same history is at GET /v2/messages/{id}/status-history.
Costs
Meta charges for some WhatsApp messages, by category and country. Gauge passes those fees through at cost, with no markup, exactly as for messages sent from the console.
Recipient numbers
Send to numbers in international (E.164) format: +447700900123. Gauge normalises them for
WhatsApp.