Send WhatsApp

API reference for sending WhatsApp template and session messages.

Send a WhatsApp message through the PlatformXe multi-provider fallback chain. Supports both pre-approved template messages and free-form session messages.

Endpoint

POST /api/v1/messaging/whatsapp

Scope: messaging:send

Request body

Field	Type	Required	Description
`to`	`string`	Yes	Recipient phone number in E.164 format (e.g. `+2348012345678`)
`templateId`	`string`	Conditional	Template identifier for template messages. Required if `message` is not provided
`templateVariables`	`Record<string, string>`	No	Key-value pairs for template placeholder substitution
`message`	`string`	Conditional	Free-form message body for session messages. Required if `templateId` is not provided
`phoneNumberId`	`string`	Yes	The WhatsApp Business phone number ID to send from

Template parameter order. WhatsApp template placeholders are positional ({{1}}, {{2}}, …). Template parameters are sent in this order:

keys that are whole numbers, in numeric order ("1", "2", … "10", "11");
then any other keys, in alphabetical order.

Name the keys "1", "2", … to match the placeholder numbers. Templates with more than 9 parameters are ordered correctly.

Session messages (using message instead of templateId) can only be sent within a 24-hour window after the recipient last messaged your WhatsApp Business number. Outside this window, you must use a template message.

Response

{
  "success": true,
  "data": {
    "messageId": "wa_abc123def456",
    "provider": "primary",
    "status": "sent",
    "sessionActive": true
  }
}

Field	Type	Description
`messageId`	`string`	Unique message identifier for tracking
`provider`	`string`	Which provider in the fallback chain handled delivery
`status`	`string`	`sent` (dispatched) or `queued` (accepted for retry)
`sessionActive`	`boolean`	Whether a 24-hour session window is currently active with the recipient

Examples

curl (template message)

curl -X POST https://api.platformxe.com/api/v1/messaging/whatsapp \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "to": "+2348012345678",
    "templateId": "order_confirmation_v2",
    "templateVariables": {
      "customerName": "Adaeze",
      "orderId": "ORD-12345",
      "total": "15,000"
    },
    "phoneNumberId": "pn_wa_001"
  }'

curl (session message)

curl -X POST https://api.platformxe.com/api/v1/messaging/whatsapp \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "to": "+2348012345678",
    "message": "Thanks for reaching out! Your support ticket #4567 has been assigned to an agent.",
    "phoneNumberId": "pn_wa_001"
  }'

SDK (template message)

import { PlatformXeClient } from '@caldera/platformxe-sdk';

const px = new PlatformXeClient({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.whatsapp.send({
  to: '+2348012345678',
  templateId: 'order_confirmation_v2',
  templateVariables: {
    customerName: 'Adaeze',
    orderId: 'ORD-12345',
    total: '15,000',
  },
  phoneNumberId: 'pn_wa_001',
});

console.log(result.data.messageId);
// "wa_abc123def456"

SDK (session message)

const result = await px.whatsapp.send({
  to: '+2348012345678',
  message: 'Thanks for reaching out! Your support ticket #4567 has been assigned to an agent.',
  phoneNumberId: 'pn_wa_001',
});

console.log(result.data.sessionActive);
// true

Use template messages for initial outreach and notifications. Session messages are best suited for follow-up replies within an active conversation.

Error responses

Code	Description
`BAD_REQUEST`	Missing required fields, or both `templateId` and `message` provided
`SESSION_EXPIRED`	Attempted to send a session message outside the 24-hour window
`TEMPLATE_NOT_FOUND`	The specified `templateId` does not exist or is not approved
`FORBIDDEN`	API key does not have the `messaging:send` scope
`RATE_LIMITED`	Rate limit exceeded for this API key
`PROVIDER_ERROR`	All providers in the fallback chain failed