PingStack | Enterprise WhatsApp Notifications

Messaging Overview

The Messages API allows sending individual WhatsApp messages to customers. When an outbound message is dispatched: 1. It is validated against plan template sending quotas (`checkTemplateSendLimit`). 2. Phone numbers are normalized into standard format with country code (e.g. `919876543210`). 3. Existing contacts are linked or automatically created on the fly. 4. The message is persisted in the `messages` table and enqueued into BullMQ `message-queue`. 5. The worker delivers the message to Meta Cloud API with circuit-breaker protection and exponential retries.

Template Positional Variables

Meta WhatsApp templates use numbered positional placeholders: `{{1}}`, `{{2}}`, `{{3}}`, etc. You can provide variables as: * **A JSON Object**: `{ "1": "Rahul", "2": "2500" }` * **A JSON Array**: `["Rahul", "2500"]` *Note: Do not assume Var 1 means "name" unless your approved template specifically expects a name in slot 1.*

Positional Variables Object

{
  "to": "919876543210",
  "template": {
    "name": "fee_reminder",
    "language": "en_US"
  },
  "variables": {
    "1": "Rahul Sharma",
    "2": "₹2,500"
  }
}

Send Message Endpoint

`POST /api/v1/messages`

Field	Type	Required	Description
to	string	Yes	Recipient phone number with country code (e.g. 919876543210).
template	string \| object	Conditional	Template name or object { name, language }. Required for template sends.
variables	object \| array	No	Positional variables for template placeholders {{1}}, {{2}}, etc.
text	string	Conditional	Direct session text body (allowed when 24h service window is active).
language	string	No	Template language code. Defaults to "en_US".

curl -X POST https://app.pingstack.in/api/v1/messages \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-tx-99124" \
  -d '{
    "to": "919876543210",
    "template": "fee_reminder",
    "variables": ["Rahul", "₹2,500"]
  }'

List Messages

`GET /api/v1/messages?page=1&pageSize=50&status=sent&phone=919876543210`

cURL

curl "https://app.pingstack.in/api/v1/messages?page=1&pageSize=20&status=delivered" \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY"

Get Message Details

`GET /api/v1/messages/{id}`

cURL

curl https://app.pingstack.in/api/v1/messages/8b9e6722-1d54-4a2e-b6a1-cb9e4f509d2a \
  -H "Authorization: Bearer ps_secret_live_YOUR_API_KEY"