WhatsApp API reference

Send one message.

curl -X POST https://msg.sisplerp.com/api/v1/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9934849371",
    "template": "fee_receipt",
    "variables": ["Riya Sharma", "4500", "R-1042"]
  }'

Response

{
  "id": "cms3x...",
  "waMessageId": "wamid.HBgM...",
  "conversationId": "cms3y...",
  "status": "sent",
  "costPaise": 78
}

Keep id — delivery webhooks reference it. to accepts 9934849371, +91 99348 49371 or 09934849371; numbers are normalised for you. variables fill {{1}}, {{2}}… in order. Send "text" instead of "template" to reply inside the 24-hour window.

A template approved with a media header or a URL button only fixes the shape. The actual file and link are chosen per send, so pass them here.

{
  "to": "9934849371",
  "template": "fee_receipt",
  "variables": ["Riya Sharma", "4500"],
  "headerMediaUrl": "https://erp.yourschool.in/receipts/8891.pdf",
  "headerFileName": "Receipt-8891.pdf",
  "buttonUrlParam": "8891"
}

Put links in a URL button rather than a body variable. Meta reviews templates with URLs in the body far more harshly, and a button is what recipients expect to tap.

A URL button cannot change domain

buttonUrlParam replaces only the {{1}} at the end of the approved URL. The domain and path are fixed at approval — passing a full URL does not redirect anywhere, it is appended as a path segment. A template approved with https://a.example.com/receipt/{{1}} can never point at b.example.com.

This matters if one template must serve several schools on different domains. It cannot. Either attach the file instead (below), or route every link through one stable host that redirects onward.

Attaching a PDF instead

A DOCUMENT header fixes only the format, never the file — so headerMediaUrl may be any domain, different on every send. That makes one approved template usable by every school, which a URL button cannot do. The file is also saved to the recipient's phone, with no link to expire.

{
  "to": "9934849371",
  "template": "fee_receipt_pdf",
  "language": "en",
  "variables": ["Aarav Sharma", "2 A", "R-004821", "30 Jul 2026",
                "April, May, June", "12,600", "R.P.K PUBLIC SCHOOL"],
  "headerMediaUrl": "https://erp.yourschool.in/r/9f3a1c7e-4b21-4e88-9c05-2ad7f1e6b0c4.pdf",
  "headerFileName": "Receipt-R-004821.pdf"
}

Requirements for the file URL

Meta fetches this URL from its own servers, not from the recipient's phone. Everything below follows from that.

• Public, no authentication. Behind a login, session cookie, VPN, firewall or IP allowlist it will fail — as will localhost or an internal hostname.
• Serve the bytes directly: 200 OK with Content-Type: application/pdf. Not an HTML viewer page, not a redirect to a login.
• Use an unguessable path. Because the file must be public, /receipt/1042 lets anyone walk 1041, 1043 and read other people's records. Use a random UUID or a signed token per file, and expire it if you can.
• One URL per file. Do not reuse a path that serves different content over time — Meta may cache by URL and deliver a stale file.
• Always send headerFileName, ending in .pdf. Without it WhatsApp shows the raw URL as the document name.
• Keep it small. The ceiling is 100 MB for a PDF, 5 MB for an image, 16 MB for a video — but a receipt should be well under 1 MB, or Meta's fetch can time out.
• Live at the moment of sending. If you generate the file lazily on first request, confirm that path works for an anonymous caller.

If a public URL is not acceptable, upload the file to Meta yourself and pass headerMediaId instead — nothing is exposed, and ids stay valid about 30 days.

Meta validates each value in variables and rejects the send — not the template — if any of these are broken. Realistic when a value comes from a remarks field or a spreadsheet import, so sanitise before sending.

• No line breaks and no tab characters
• No four or more consecutive spaces
• Send exactly as many values as the template has variables, in order
• Never omit a position — every later value shifts up if you do

$clean = preg_replace('/\s+/', ' ', trim($value));

Call GET /templates for variableCount rather than hardcoding it — a template edited later may take a different number.

Up to 200 recipients per request.

{
  "template": "fee_reminder",
  "recipients": [
    { "to": "9934849371", "variables": ["Riya", "4500"] },
    { "to": "7053978898", "variables": ["Amit", "3200"] }
  ]
}

Same message to everyone? Use "to": [numbers] with one shared variables array.

Each recipient can carry its own file and link — what a receipt run needs, since every parent gets a different PDF:

{
  "template": "fee_receipt",
  "recipients": [
    { "to": "9934849371", "variables": ["Riya", "4500"],
      "headerMediaUrl": "https://erp.yourschool.in/receipts/8891.pdf",
      "headerFileName": "Receipt-8891.pdf",
      "buttonUrlParam": "8891" }
  ]
}

Returns HTTP 207 when some succeeded and some failed, with a results array giving the outcome per number. Treat 207 as partial success, not failure.

Delivery status: sent → delivered → read, or failed. Accepts our id or Meta's waMessageId.

Approved templates and how many variables each takes. Call this at startup rather than hardcoding names.

{ "templates": [
  { "name": "fee_receipt", "language": "en", "status": "APPROVED",
    "body": "Hi {{1}}, we received Rs {{2}}. Receipt {{3}}.",
    "variableCount": 3 }
]}

List contacts. Filter with ?tag=class-8a, page with the returned nextCursor.

Create or update a contact, keyed on the number.

{ "waId": "9934849371", "name": "Riya's mother",
  "tags": ["class-8a", "parent"],
  "attributes": { "studentId": "S-1042" } }

Optional — sending creates the contact automatically. Useful so the inbox shows real names and tags can be used as broadcast audiences.