SMS & WhatsApp Overview
Transactional SMS (multi-provider fallback) and WhatsApp (click-to-chat URLs today, Meta Cloud API on the roadmap).
The PlatformXe SMS & WhatsApp service ships two channels with two very different models — be sure to pick the right path for your use case.
SMS
Transactional SMS through a multi-provider fallback chain. The primary provider is Termii; backups are Twilio and Africa's Talking. Each provider has its own circuit breaker so a single outage automatically routes traffic to the next in the chain.
| Type | Description |
|---|---|
| Transactional SMS | One-way text messages (OTPs, alerts, notifications) |
Status: Coming Soon — the dispatcher is wired in, provider procurement is in progress.
PlatformXe supports two operating modes for WhatsApp; the active mode is selected by the PLATFORMXE_WHATSAPP_MODE environment variable.
| Mode | Description | Status |
|---|---|---|
click_to_chat (default) | PlatformXe builds wa.me / whatsapp:// URLs with the recipient + message pre-encoded. Your app surfaces those URLs to the operator (e.g. as an "Open WhatsApp" button) and the operator's own WhatsApp Desktop / mobile app handles the actual send. No backend dispatch, no Meta credentials, no rate limit. | Live |
meta_cloud_api | Sends route through Meta's WhatsApp Business Cloud API. Requires a registered Meta WhatsApp Business account + WHATSAPP_TOKEN + WHATSAPP_PHONE_NUMBER_ID. Supports template-based + session messages. | Reserved for the future cutover |
Today (click_to_chat): PlatformXe is NOT a WhatsApp sender. It returns the URL the operator clicks; the actual send happens on the operator's own device. This avoids the cost + compliance overhead of operating a Meta Business account while still giving your app a single API to call.
Migration to Meta Cloud API: when you're ready to send programmatically (templates, session messages, automated flows), provision a Meta WABA, set WHATSAPP_TOKEN + WHATSAPP_PHONE_NUMBER_ID, and flip PLATFORMXE_WHATSAPP_MODE=meta_cloud_api. The endpoints stay the same.
How POST /api/v1/messaging/whatsapp works in click-to-chat mode
- Your app sends
{ to, message }to the endpoint. - PlatformXe builds the click-to-chat URLs and logs the issue to
transactional_message_log(status=SENT, provider=click_to_chat). - The response carries
clickToChatUrl+deepLinkinstead of a MetamessageId. - Your UI surfaces the URLs to the operator (anchor tag, button, etc.).
- The operator clicks → their WhatsApp Desktop / mobile app opens with the chat pre-populated → they hit Send.
If you only need the URL and don't want PlatformXe to log it, call POST /api/v1/messaging/whatsapp/link instead — pure transform, no audit log.
API scope
All messaging endpoints require the messaging:send scope on your API key.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/messaging/sms | Send an SMS (Coming Soon). |
| POST | /api/v1/messaging/whatsapp | Dispatch a WhatsApp message. In click_to_chat mode returns clickToChatUrl + deepLink; in meta_cloud_api mode returns a Meta messageId. Audit-logged. |
| POST | /api/v1/messaging/whatsapp/link | Build a click-to-chat URL pair without side effects. Pure transform, no audit log. |
| GET | /api/v1/messaging/whatsapp/health | Diagnostic probe. Surfaces the active operating mode, per-check results, and the most recent FAILED rows from transactional_message_log. Use this when sends aren't behaving the way you expect. |
Next steps
- Send SMS -- API reference for sending SMS messages
- Send WhatsApp -- API reference for sending WhatsApp messages