Watily Developer Docs: WhatsApp, Loyalty & Webhooks API Skip to content
REST API · v1

Build on WhatsApp and loyalty with the Watily API

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.

  • Bearer or X-Api-Key auth
  • HMAC-signed webhooks
  • OpenAPI 3 and Postman
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"
  }'
What the API covers

Most of the Watily dashboard, available in code

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).

Contacts & campaigns

Import up to 500 contacts per call, segments, and create, start, pause and resume campaigns from your system.

Inbox

Read conversations and messages, assign them to agents, archive, tag, and track connected lines and analytics.

Loyalty & POS

One call from the till enrolls the customer and adds the stamp or points with no duplicates, plus reversals and wallet notifications.

Real-time events

12 events pushed to your URL: incoming messages, delivery status, campaigns, loyalty, and QR line connect and disconnect.

Scoped security

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.

Quickstart

From account to first message in three steps

Create an account and connect a line

Sign up for Watily and connect a WhatsApp number officially or by QR.

Create an API key

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).

Make your first call

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

HTTPMeaning
401invalid_api_key — missing, malformed or revoked key
403insufficient_scope / subscription_expired / quota_exceeded / store_forbidden / module_not_in_plan
402wallet_insufficient — official-line wallet cannot cover the send
409not_connected / line_banned / idempotency_in_flight / contact_exists / recipient_opted_out — the last one only with respect_opt_out=true
422invalid_phone — messages need 10 to 15 digits, contacts at least 9. Field validation errors use {message, errors} with no code
429rate_limited — rate limit exceeded (wait Retry-After seconds) / governor_blocked — the line hit its sending ceiling, retry later
503send_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.

Endpoints

Every route under /api/v1

Each route lists the scope your key needs. Full field and response details are in the interactive reference.

Messages & media

MethodPathScopeDescription
POST/messagesmessages:sendSend a WhatsApp message (text, media, document, audio, video, interactive, location; templates and emoji reactions on official lines only)
POST/mediamessages:sendUpload a file (max 16 MB, deleted after 7 days) to send later via media_id
GET/templatesmessages:sendList approved Meta templates (for sending on official lines)

Contacts & segments

MethodPathScopeDescription
GET/contactscontacts:readList contacts
GET/contacts/{phone}contacts:readGet a contact by phone
GET/contacts/{phone}/existscontacts:readDoes the number have WhatsApp (QR lines only; official lines answer 501)
POST/contactscontacts:writeCreate a contact
PATCH/contacts/{phone}contacts:writeUpdate a contact
POST/contacts/importcontacts:writeBulk import up to 500 per call
POST/contacts/{phone}/unsubscribecontacts:writeUnsubscribe from marketing
POST/contacts/{phone}/resubscribecontacts:writeResubscribe
GET/segmentscontacts:readList segments
POST/segmentscontacts:writeCreate a segment

Campaigns

MethodPathScopeDescription
POST/campaignscampaigns:writeCreate a draft campaign for a list of phones (up to 1000) or a segment_id
GET/campaigns/{campaign}campaigns:readGet a campaign
POST/campaigns/{campaign}/startcampaigns:writeStart (optional refresh_audience re-resolves the segment audience)
POST/campaigns/{campaign}/pausecampaigns:writePause
POST/campaigns/{campaign}/resumecampaigns:writeResume

Conversations, lines & analytics

MethodPathScopeDescription
GET/conversationsconversations:readList inbox conversations
GET/conversations/{id}conversations:readGet a conversation
GET/conversations/{id}/messagesconversations:readList its messages
POST/conversations/{id}/assignconversations:writeAssign or unassign
POST/conversations/{id}/tagsconversations:writeReplace tags (an empty array clears them)
POST/conversations/{id}/archiveconversations:writeArchive
POST/conversations/{id}/unarchiveconversations:writeUnarchive
POST/conversations/{id}/readconversations:writeMark as read
GET/instancesconversations:readWhatsApp lines and their connection status
GET/analytics/summaryconversations:readUsage summary for a range (last 30 days by default)

Loyalty & POS

MethodPathScopeDescription
POST/loyalty/stampsloyalty:writePOS flow: enroll + card + stamp in one call
POST/loyalty/stamps/reverseloyalty:writeReverse a stamp recorded via /loyalty/stamps by its idempotency_key
POST/loyalty/pointsloyalty:writePOS flow: enroll + award points in one call
POST/loyalty/points/reverseloyalty:writeReverse a points award
POST/loyalty/membersloyalty:writeEnroll a member (idempotent by phone), optionally with a stamp card
POST/loyalty/members/{phone}/pointsloyalty:writeAward points to an existing member (no auto-enroll)
POST/loyalty/members/{phone}/stampsloyalty:writeStamp an existing member (legacy flow, prefer /loyalty/stamps)
GET/loyalty/programsloyalty:readActive programs
GET/loyalty/members/{phone}loyalty:readGet a member
GET/loyalty/members/{phone}/pointsloyalty:readQuick balance and level check
GET/loyalty/members/{phone}/transactionsloyalty:readTransaction history
GET/loyalty/members/{phone}/wallet-cardloyalty:readApple / Google Wallet card links
GET/loyalty/cards/{cardNumber}loyalty:readLook up by printed or scanned card number
POST/loyalty/notificationsloyalty:notifyWallet lock-screen notification to chosen customers or a whole segment (try dry_run first)
GET/loyalty/notificationsloyalty:readNotification batches (last 10 within 30 days)

Webhooks

MethodPathScopeDescription
GET/webhookswebhooks:manageList endpoints
POST/webhookswebhooks:manageRegister an endpoint (secret returned once)
PATCH/webhooks/{id}webhooks:manageUpdate (URL, events, enabled)
DELETE/webhooks/{id}webhooks:manageDelete
POST/webhooks/{id}/testwebhooks:manageSend 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.

Scopes

Give every integration the least access it needs

ScopeAllows
messages:sendSend messages, upload media, read templates
contacts:readRead contacts and segments
contacts:writeCreate and edit contacts and segments
campaigns:readRead campaigns
campaigns:writeCreate and control campaigns
conversations:readRead conversations, lines and analytics
conversations:writeAssign, archive, tag and mark conversations as read
loyalty:readRead loyalty data
loyalty:writeEnroll members, record and reverse stamps and points
loyalty:notifyWallet notifications (separate scope on purpose)
webhooks:manageManage webhooks

Example: a POS system needs loyalty:write and loyalty:read only, so if its key leaks it cannot send messages or read conversations.

Recipes

What developers build most

Post a stamp from the till

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"
  }'

Register a webhook

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"]
  }'
Webhooks

Receive events and verify their signature

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.

message.incomingmessage.statuscampaign.completedcontact.unsubscribedcontact.resubscribedloyalty.visit.recordedloyalty.reward.unlockedloyalty.visit.reversedloyalty.points.awardedloyalty.points.reversedinstance.connectedinstance.disconnected
<?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);

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).

FAQ

Developer questions

How do I get an API key?

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.

What is the base URL and how do I authenticate?

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).

Are there rate limits?

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.

Can I receive incoming messages and updates in real time?

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.

Does the API cover loyalty and POS?

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.

Is there an OpenAPI spec or Postman collection?

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.

Does sending differ by connection type?

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.

Ready to integrate?

Create your account, grab your key, and message us on WhatsApp if you need help wiring up your system.

WhatsApp Start now