WhatsApp messaging

Waasl connects to the WhatsApp Business Platform (Cloud API). Meta’s rules apply to everything you send; Waasl enforces them up front so you get a clear error instead of a silent failure.

The 24-hour customer service window

Each time a contact messages you, a 24-hour window opens. Inside it you may send any message kind. When it closes, you can only send an approved template. Every conversation exposes window_expires_at so you can decide what to send.

You send	Window open	Window closed
`text`, `image`, `file`, `voice`	✅	❌ `409 window_closed`
`template`	✅	✅

Templates

Templates are pre-approved message formats with numbered variables:

مرحبا {{1}}، طلبك رقم {{2}} جاهز للتوصيل 🚚

Create one with POST /whatsapp/templates. Meta reviews it — usually within minutes — and Waasl sends template.status_updated with the result. Send it by name and language, with params in order:

{ "kind": "template", "template": { "name": "order_ready", "language": "ar", "params": ["سارة", "4821"] } }

Categories matter for pricing and approval: utility (order updates, reminders), authentication (one-time codes) and marketing (everything promotional). Marketing templates require the contact’s opt-in — set consents.whatsapp_marketing on the contact.

Media

Upload once with POST /media, then send by media_id:

{ "kind": "image", "media_id": "med_k2Pz8", "body": "قائمة هذا الأسبوع" }

Kind	Types	Max size
`image`	JPEG, PNG	5 MB
`video` (coming soon)	MP4, 3GPP	16 MB
`voice`	OGG/Opus, AAC, MP3, AMR	16 MB
`file`	PDF, Office docs, any	100 MB

Media your contacts send you is stored by Waasl; download it with GET /media/{media_id}.

Delivery statuses

Sending is asynchronous. A message moves through:

queued → sent → delivered → read
             ↘ failed (with error)

Subscribe to message.status_updated instead of polling. A failed message carries Meta’s reason in error, e.g. Re-engagement message (131047) when the window had closed.

When Waasl refuses to send

`code`	Meaning	Fix
`window_closed`	The 24-hour window has closed	Send a template
`conversation_closed`	The conversation is closed	Reopen it first, or send to the phone number via `POST /messages`
`contact_blocked`	The contact is blocked	Unblock with `PATCH /contacts/{id}`
`bot_in_control`	An AI agent or workflow is handling it	Hand over to a human
`template_not_found`	No approved template with that name and language	Check `GET /whatsapp/templates?status=approved`
`media_not_found`	Unknown `media_id`	Upload again

Other channels

Instagram, Messenger, SMS, email and web chat are coming soon. They will use the same contacts, conversations and messages endpoints — channel_type tells them apart — so code you write for WhatsApp today carries over.