Developers
WhatsApp for any system, in one API call
HeyPing is the one WhatsApp connection behind HeyShop, HeyPOS, HeyInvoice and Collie. Your own systems can use it too, with the same guard rails.
Quick start
Three steps
Base URL: https://portal.heyping.heysheep.sg/api
Create a key
In HeyPing, open Developers in your workspace, name the key (for example “HeyShop”) and tick only the permissions it needs.
Send a message
Call POST /v1/messages with an approved template. Add an Idempotency-Key so a retry never sends twice.
Listen for updates
Add a webhook address to get delivered, read, replies and opt-outs, signed with your secret.
POST /api/v1/messagesAuthorization: Bearer hp_live_••••••••Idempotency-Key: shop-order-10482-shipped{ "to": "+6591234567", "template": "order_shipped", "params": { "first_name": "Mei", "order_no": "10482", "courier": "Ninja Van" }}// 202 Accepted{ "id": "hpm_8f2c1a…", "status": "queued"}Reference
Endpoints
Authenticate with Authorization: Bearer hp_live_… on every call.
| Endpoint | What it does |
|---|---|
| GET/v1/workspace/status | Is WhatsApp connected and ready to send? |
| POST/v1/contacts | Add or update a customer, with their consent |
| GET/v1/contacts/{phone} | Look up a customer and their WhatsApp status |
| POST/v1/messages | Send an approved template message |
| GET/v1/messages/{id} | Status and history of a message |
| GET/v1/templates | Approved templates and their variables |
Permissions
Scoped API keys
Each key only does what you allow. A billing system that only sends invoices can never send a promotion.
- messages.send.utility
- Send order updates, receipts and other service messages
- messages.send.marketing
- Send promotions and offers
- messages.send.authentication
- Send one-time passcodes
- messages.read
- Check the status of messages it sent
- contacts.read
- Look up customers and their WhatsApp status
- contacts.write
- Add or update customers and their consent
- templates.read
- List approved message templates
Webhooks
Signed events
Retried with backoff if your server is down. Verify every event with your webhook secret.
- message.status
- A message was sent, delivered, read or failed
- message.inbound
- A customer sent a message
- contact.opted_out
- A customer stopped messages
- template.status_changed
- A template was approved, rejected or paused
- number.quality_changed
- Your WhatsApp number's quality rating changed
import { createHmac, timingSafeEqual } from "node:crypto";// X-HeyPing-Timestamp and X-HeyPing-Signature headersfunction isFromHeyPing(rawBody, timestamp, signature, secret) { const age = Date.now() / 1000 - Number(timestamp); if (age > 300) return false; // older than 5 minutes const expected = createHmac("sha256", secret) .update(`${timestamp}.${rawBody}`) .digest("hex"); const given = signature.replace("sha256=", ""); return given.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(given));}Built-in checks
Every send is checked for you
- The key has permission for this kind of message
- The customer agreed and hasn't opted out
- The template is approved and the right category
- The WhatsApp number is connected and healthy
- Duplicate requests with the same Idempotency-Key send once
- TypeScript SDK (@heyping/sdk) for Node.js apps