WhatsApp Business
Send text, media, documents, interactive messages and locations on official and QR lines, plus templates and emoji reactions on official lines only, with an optional opt-out guard (respect_opt_out).
Send WhatsApp messages, manage contacts, campaigns and conversations, post loyalty points from the till and receive events in real time through signed webhooks. 48 endpoints with scoped keys, an OpenAPI spec and a Postman collection.
curl -X POST https://site.watily.com/api/v1/messages \
-H "Authorization: Bearer wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"to": "966501234567",
"type": "text",
"message": "Hi! Your order #1042 is ready for pickup"
}'
Send text, media, documents, interactive messages and locations on official and QR lines, plus templates and emoji reactions on official lines only, with an optional opt-out guard (respect_opt_out).
Import up to 500 contacts per call, segments, and create, start, pause and resume campaigns from your system.
Read conversations and messages, assign them to agents, archive, tag, and track connected lines and analytics.
One call from the till enrolls the customer and adds the stamp or points with no duplicates, plus reversals and wallet notifications.
12 events pushed to your URL: incoming messages, delivery status, campaigns, loyalty, and QR line connect and disconnect.
Each key has specific scopes and its own request counters, is bound to one store, can be revoked instantly from the dashboard, and only a hash of it is stored on our side so it cannot be recovered.
Sign up for Watily and connect a WhatsApp number officially or by QR.
Go to WhatsApp, Integrations, the API Keys tab. Pick only the scopes you need. Keys start with wtly_live_ and are shown in full once (up to 10 active keys per company, each bound to one store).
Use the example above or import the Postman collection. Base URL: https://site.watily.com/api/v1
Authentication — either header works (if both are sent, Bearer wins):
Authorization: Bearer wtly_live_xxxxxxxx
# or
X-Api-Key: wtly_live_xxxxxxxx
Common errors
| HTTP | Meaning |
|---|---|
| 401 | invalid_api_key — missing, malformed or revoked key |
| 403 | insufficient_scope / subscription_expired / quota_exceeded / store_forbidden / module_not_in_plan |
| 402 | wallet_insufficient — official-line wallet cannot cover the send |
| 409 | not_connected / line_banned / idempotency_in_flight / contact_exists / recipient_opted_out — the last one only with respect_opt_out=true |
| 422 | invalid_phone — messages need 10 to 15 digits, contacts at least 9. Field validation errors use {message, errors} with no code |
| 429 | rate_limited — rate limit exceeded (wait Retry-After seconds) / governor_blocked — the line hit its sending ceiling, retry later |
| 503 | send_unavailable / send_outcome_unknown — the second means the message may already have been delivered: check its status before resending |
Limits per key: 120 requests/min shared by all reads (GET) and 60/min shared by all writes and sends (POST, PATCH, DELETE), which may vary by plan. Going over returns 429 with a Retry-After header.
Response shape: success is {"status":"success","data":{...}} (some routes also add "ok": true); errors are {"status":"error","code":"...","message":"..."} with ok=false on most routes, and 422 validation errors use {"message","errors"}. Phone numbers are normalised automatically (the 966 country code is assumed unless the number starts with a known international prefix), so 0501234567 becomes 966501234567, while contacts are stored in the format you sent.
Each route lists the scope your key needs. Full field and response details are in the interactive reference.
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /messages | messages:send | Send a WhatsApp message (text, media, document, audio, video, interactive, location; templates and emoji reactions on official lines only) |
| POST | /media | messages:send | Upload a file (max 16 MB, deleted after 7 days) to send later via media_id |
| GET | /templates | messages:send | List approved Meta templates (for sending on official lines) |
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /contacts | contacts:read | List contacts |
| GET | /contacts/{phone} | contacts:read | Get a contact by phone |
| GET | /contacts/{phone}/exists | contacts:read | Does the number have WhatsApp (QR lines only; official lines answer 501) |
| POST | /contacts | contacts:write | Create a contact |
| PATCH | /contacts/{phone} | contacts:write | Update a contact |
| POST | /contacts/import | contacts:write | Bulk import up to 500 per call |
| POST | /contacts/{phone}/unsubscribe | contacts:write | Unsubscribe from marketing |
| POST | /contacts/{phone}/resubscribe | contacts:write | Resubscribe |
| GET | /segments | contacts:read | List segments |
| POST | /segments | contacts:write | Create a segment |
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /campaigns | campaigns:write | Create a draft campaign for a list of phones (up to 1000) or a segment_id |
| GET | /campaigns/{campaign} | campaigns:read | Get a campaign |
| POST | /campaigns/{campaign}/start | campaigns:write | Start (optional refresh_audience re-resolves the segment audience) |
| POST | /campaigns/{campaign}/pause | campaigns:write | Pause |
| POST | /campaigns/{campaign}/resume | campaigns:write | Resume |
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /conversations | conversations:read | List inbox conversations |
| GET | /conversations/{id} | conversations:read | Get a conversation |
| GET | /conversations/{id}/messages | conversations:read | List its messages |
| POST | /conversations/{id}/assign | conversations:write | Assign or unassign |
| POST | /conversations/{id}/tags | conversations:write | Replace tags (an empty array clears them) |
| POST | /conversations/{id}/archive | conversations:write | Archive |
| POST | /conversations/{id}/unarchive | conversations:write | Unarchive |
| POST | /conversations/{id}/read | conversations:write | Mark as read |
| GET | /instances | conversations:read | WhatsApp lines and their connection status |
| GET | /analytics/summary | conversations:read | Usage summary for a range (last 30 days by default) |
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /loyalty/stamps | loyalty:write | POS flow: enroll + card + stamp in one call |
| POST | /loyalty/stamps/reverse | loyalty:write | Reverse a stamp recorded via /loyalty/stamps by its idempotency_key |
| POST | /loyalty/points | loyalty:write | POS flow: enroll + award points in one call |
| POST | /loyalty/points/reverse | loyalty:write | Reverse a points award |
| POST | /loyalty/members | loyalty:write | Enroll a member (idempotent by phone), optionally with a stamp card |
| POST | /loyalty/members/{phone}/points | loyalty:write | Award points to an existing member (no auto-enroll) |
| POST | /loyalty/members/{phone}/stamps | loyalty:write | Stamp an existing member (legacy flow, prefer /loyalty/stamps) |
| GET | /loyalty/programs | loyalty:read | Active programs |
| GET | /loyalty/members/{phone} | loyalty:read | Get a member |
| GET | /loyalty/members/{phone}/points | loyalty:read | Quick balance and level check |
| GET | /loyalty/members/{phone}/transactions | loyalty:read | Transaction history |
| GET | /loyalty/members/{phone}/wallet-card | loyalty:read | Apple / Google Wallet card links |
| GET | /loyalty/cards/{cardNumber} | loyalty:read | Look up by printed or scanned card number |
| POST | /loyalty/notifications | loyalty:notify | Wallet lock-screen notification to chosen customers or a whole segment (try dry_run first) |
| GET | /loyalty/notifications | loyalty:read | Notification batches (last 10 within 30 days) |
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /webhooks | webhooks:manage | List endpoints |
| POST | /webhooks | webhooks:manage | Register an endpoint (secret returned once) |
| PATCH | /webhooks/{id} | webhooks:manage | Update (URL, events, enabled) |
| DELETE | /webhooks/{id} | webhooks:manage | Delete |
| POST | /webhooks/{id}/test | webhooks:manage | Send a test message.incoming event (data.test = true) |
Note: the Automation Journeys API was removed and its old route answers 410. Use the Growth Engine abandoned-cart automation instead.
| Scope | Allows |
|---|---|
| messages:send | Send messages, upload media, read templates |
| contacts:read | Read contacts and segments |
| contacts:write | Create and edit contacts and segments |
| campaigns:read | Read campaigns |
| campaigns:write | Create and control campaigns |
| conversations:read | Read conversations, lines and analytics |
| conversations:write | Assign, archive, tag and mark conversations as read |
| loyalty:read | Read loyalty data |
| loyalty:write | Enroll members, record and reverse stamps and points |
| loyalty:notify | Wallet notifications (separate scope on purpose) |
| webhooks:manage | Manage webhooks |
Example: a POS system needs loyalty:write and loyalty:read only, so if its key leaks it cannot send messages or read conversations.
One request enrolls the customer, issues the card and adds the stamp (program_id may be omitted only when the store has exactly one active stamp program). Re-sending the same idempotency_key never doubles it. Note: issuing a new card sends the customer a WhatsApp template once, so do not bulk-replay old orders.
curl -X POST https://site.watily.com/api/v1/loyalty/stamps \
-H "X-Api-Key: wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"phone": "966501234567",
"program_id": 12,
"idempotency_key": "pos-order-882",
"amount": 45.5,
"branch": "Main branch"
}'
The URL must be public HTTPS. Keep the secret returned in the response (data.secret); it is shown once. Omit events (or send them empty) to subscribe to all; the maximum is 5 endpoints per company.
curl -X POST https://site.watily.com/api/v1/webhooks \
-H "Authorization: Bearer wtly_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/watily-hook",
"events": ["message.incoming", "message.status"]
}'
Each delivery carries the headers X-Watily-Event X-Watily-Delivery X-Watily-Signature. The signature is sha256=HMAC_SHA256(raw_body, secret) (hex), where the secret is the whole string including the whsec_ prefix.
<?php
// $endpointSecret = the whole whsec_... string returned once by POST /webhooks
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WATILY_SIGNATURE'] ?? '';
$calc = 'sha256=' . hash_hmac('sha256', $raw, $endpointSecret);
if (!hash_equals($calc, $sig)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true); // $event['event'], $event['data']
// dedupe on $_SERVER['HTTP_X_WATILY_DELIVERY'] (stable across retries)
http_response_code(200);const crypto = require('crypto');
// ENDPOINT_SECRET = the whole whsec_... string returned once by POST /webhooks
app.post('/watily-hook', express.raw({ type: '*/*' }), (req, res) => {
const calc = 'sha256=' + crypto
.createHmac('sha256', ENDPOINT_SECRET)
.update(req.body).digest('hex');
const sig = req.get('X-Watily-Signature') || '';
if (sig.length !== calc.length ||
!crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(sig))) {
return res.sendStatus(401);
}
const evt = JSON.parse(req.body); // evt.event, evt.data
// dedupe on req.get('X-Watily-Delivery') (stable across retries)
res.sendStatus(200);
});{
"event": "message.incoming",
"timestamp": "2026-08-14T10:00:00+03:00",
"company_id": 123,
"data": {
"phone": "966551234567",
"customer_name": "Ahmed",
"message_text": "Hello",
"instance_id": "abc123",
"raw_remote_jid": "966551234567@s.whatsapp.net",
"wa_message_id": "wamid.HBgL..."
}
}Compute the signature on the raw body before any JSON parsing, compare it with a constant-time function (check the lengths match first) and answer with any 2xx within 10 seconds. 3xx redirects are not followed and count as failures; up to 4 attempts are made in total (retries after 30 seconds, 5 minutes and 30 minutes). Delivery is at-least-once and unordered, so deduplicate on the X-Watily-Delivery header (stable across retries). The timestamp field is in Riyadh time (+03:00).
In the Watily dashboard go to WhatsApp, then Integrations, then the API Keys tab. Create a key and tick only the scopes your integration needs; each key is bound to one store (up to 10 active keys per company). The full key is shown once at creation, so store it safely because we only keep its hash; you can revoke it at any time and it stops working immediately.
The base URL is https://site.watily.com/api/v1. Send the key as an Authorization Bearer header or in an X-Api-Key header; both behave the same (if both are sent, Bearer wins).
Yes. Each key gets 120 requests per minute shared by all reads (GET) and 60 per minute shared by all writes and sends (POST, PATCH, DELETE), which can vary by plan. Going over returns HTTP 429 with a Retry-After header telling you how many seconds to wait.
Yes, through webhooks: register a public HTTPS URL (up to 5 per company) and choose events (incoming message, message status, campaign completed, unsubscribes and resubscribes, loyalty events, QR line connected or disconnected). Every delivery is signed with an X-Watily-Signature header: sha256= followed by the HMAC-SHA256 of the raw body, keyed with the whole secret including the whsec_ prefix. Any 2xx within 10 seconds counts as success; otherwise it is retried up to 4 attempts in total (after 30 seconds, 5 minutes and 30 minutes). Delivery is at-least-once, so deduplicate on the X-Watily-Delivery header.
Yes. A one-call flow for tills and ERPs enrolls the customer and adds the stamp or points, an idempotency_key prevents double-posting, and there are endpoints to reverse, check balances, fetch wallet-card links and push lock-screen notifications. Note that issuing a new stamp card sends the customer a WhatsApp template once, and every stamp or points change updates an installed wallet pass.
Yes. The full browsable reference, an OpenAPI 3 spec and a ready Postman collection are available from the reference page, and we update them with API changes.
The same request works on official lines (Meta Cloud API) and QR lines, but templates and emoji reactions are available on official lines only, and free-form messages on an official line are only deliverable inside Meta’s 24-hour window (outside it use a template). Every send counts against the plan’s monthly quota and returns 403 quota_exceeded once it is used up; official lines also need wallet balance, otherwise 402 wallet_insufficient.
Create your account, grab your key, and message us on WhatsApp if you need help wiring up your system.