Messages Reference

Endpoints for sending outbound WhatsApp template and session messages, handling positional variables, and querying message logs.

POST

/api/v1/messages

Dispatches a template message with positional variables or direct session text to a recipient.

Headers

Header	Required	Description
Authorization	Yes	Bearer ps_secret_live_YOUR_API_KEY
Idempotency-Key	No	Unique request key for safe network retries (24h TTL)
Content-Type	Yes	application/json

Request Body Parameters

Field	Type	Required	Description
to	string	Yes	Recipient phone number with country code (e.g. 919876543210)
template	string \| object	No	Template name or object { name, language }
variables	object \| array	No	Positional placeholders {"1": "Val", "2": "Val"} or ["Val1", "Val2"]
text	string	No	Freeform text body (allowed within active 24h customer service window)
language	string	No	Template language code (default: en_US)

Code Example (5 Languages)

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-001" \
  -d '{
    "to": "919876543210",
    "template": "fee_reminder",
    "variables": ["Rahul", "₹2,500"]
  }'

Response Example

JSON

{
  "success": true,
  "data": {
    "message_id": "8b9e6722-1d54-4a2e-b6a1-cb9e4f509d2a",
    "recipient": "919876543210",
    "status": "queued",
    "message_type": "template",
    "template": "fee_reminder",
    "created_at": "2026-09-09T22:00:00.000Z"
  },
  "request_id": "req_8a9b0c1d"
}

GET

/api/v1/messages

Returns paginated message history for your workspace with status and recipient filters.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (max: 100, default: 50)
status	string	No	Filter by status: queued, sent, delivered, read, failed
phone	string	No	Filter by recipient phone number

Code Example (5 Languages)

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

Response Example

JSON

{
  "success": true,
  "data": [
    {
      "id": "8b9e6722-1d54-4a2e-b6a1-cb9e4f509d2a",
      "phone_number": "919876543210",
      "status": "delivered",
      "direction": "outbound",
      "created_at": "2026-09-09T22:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1,
    "hasMore": false
  },
  "request_id": "req_9b0c1d2e"
}

GET

/api/v1/messages/{id}

Retrieves status, provider reference, and metadata for a specific message.

Code Example (5 Languages)

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

Response Example

JSON

{
  "success": true,
  "data": {
    "id": "8b9e6722-1d54-4a2e-b6a1-cb9e4f509d2a",
    "phone_number": "919876543210",
    "status": "read",
    "template_name": "fee_reminder",
    "content": "Dear Rahul Sharma, your pending fee of ₹2,500 is due.",
    "created_at": "2026-09-09T22:00:00.000Z"
  },
  "request_id": "req_1d2e3f4a"
}

All Reference Endpoints