WhatsApp API and Webhooks Developer Guide | Masar

Use the REST API to send messages and manage data from your system. The API applies the same quotas, management fees, and duplicate protection as the dashboard.

Base URL: https://router.atyaf.co/api/v1

Authentication

Send your API key as a bearer token on every request. The key identifies the account, so do not send an account id. A resource belonging to another account returns 404.

curl https://router.atyaf.co/api/v1/me \
  -H "Authorization: Bearer msr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A production key starts with msr_live_, followed by 48 characters and a 6-character checksum. Copy it in full when it is created.

The key is shown once when it is created and cannot be recovered later. If you lose it, revoke it and create a new key.

A key may be restricted to an address allowlist and given an expiry date. Both are refused at authentication, before anything is charged.

Scopes

Every endpoint requires one scope. Grant a key only what the integration needs. A reporting key without messages:send cannot send or spend, but it may expose account data. Revoke any leaked key immediately and issue a replacement.

Errors

Every failed response uses the same structure and includes a stable error code. Build integration logic around the code, not the message text, because messages are translated and may change.

{
  "error": {
    "code": "scope_missing",
    "message": "…",
    "request_id": "req_1a2b3c…",
    "required_scope": "messages:send"
  }
}

Every response carries a Masar-Request-Id header, repeated in the body of an error. Quote it in a support request and it resolves to exactly one call in your request log.

Rate limits

Limits are per KEY and per minute, never per IP address — two customers behind one office connection do not share a budget. Every response reports X-RateLimit-Limit and X-RateLimit-Remaining; a refusal carries Retry-After.

Idempotency

Every write that spends money or cannot be undone requires an Idempotency-Key header: POST /v1/messages, POST /v1/campaigns, and start, pause, resume and cancel on a campaign. Any unique string will do; a UUID per call is the usual choice.

This header prevents duplicate sends or reservations when your system retries after a connection failure.

• Same key, same payload: the first call's answer is replayed with Idempotent-Replayed: true, and nothing is sent or charged again.
• The same key with a different payload returns 422 with idempotency_conflict. Use a new key for every different operation.
• Same key while the first call is still running: 409 idempotency_in_flight. Retry in a moment.

The payload is fingerprinted over the NORMALISED recipient, so a retry that reformats the number replays rather than conflicting.

Endpoints

OpenAPI specification

The whole of this API is published as an OpenAPI 3.1 document at a stable URL. Point a generator at it and you get a typed client in your own language rather than a hand-written one that drifts.

https://router.atyaf.co/docs/openapi.json

The document is regenerated from available routes on every release. Every operation uses bearer authentication, and no endpoint requires an account id.

Sending a message

One approved template to one recipient. The response is 202 with the queued message; delivery is reported by webhook or by polling the message.

curl

curl -X POST https://router.atyaf.co/api/v1/messages \
  -H "Authorization: Bearer $MASAR_KEY" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
        "to": "+970599123456",
        "template_id": 12,
        "variables": ["Ahmad", "1234"]
      }'

HTTP/1.1 202 Accepted
Masar-Request-Id: req_1a2b3c…
X-RateLimit-Remaining: 119

{
  "data": {
    "id": 8417,
    "to": "+970599123456",
    "status": "queued",
    "dispatch_state": "pending",
    "price_microusd": 18100,
    "price": "0.0181"
  }
}

A 202 response means Masar accepted the message and added it to the send queue. It does not mean the message was delivered. Read the final status from the message resource or a webhook. Management fees are returned automatically if the message is not sent.

Replying in a conversation

Send `text` instead of `template_id` to reply to someone who wrote to you. No template is required, and Masar does not deduct a management fee for this reply. Any Meta charge appears in your Meta business account.

curl -X POST https://router.atyaf.co/api/v1/messages   -H "Authorization: Bearer $MASAR_KEY"   -H "Idempotency-Key: reply-8417"   -H "Content-Type: application/json"   -d '{
    "to": "+970599123456",
    "text": "Your order is on its way."
  }'

Only within 24 hours of that person’s last message to you. Outside it the call is refused with `service_window_closed` before anything is charged, and an approved template is the way through.

A message that arrived with a photograph or a document carries a media id. Fetch the bytes with: GET https://router.atyaf.co/api/v1/media/{id}

PHP

<?php

$response = Http::withToken($key)
    ->withHeaders(['Idempotency-Key' => 'order-1234'])
    ->post('https://router.atyaf.co/api/v1/messages', [
        'to' => '+970599123456',
        'template_id' => 12,
        'variables' => ['Ahmad', '1234'],
    ]);

if ($response->header('Idempotent-Replayed') === 'true') {
    // This retry sent nothing and charged nothing. The body is the
    // original call's answer.
}

$messageId = $response->json('data.id');

Webhooks

We POST signed events to your URL. Deliveries follow Standard Webhooks, so any conforming library verifies them without custom code.

Three headers travel with every delivery:

The signature is HMAC-SHA256 over the id, timestamp, and raw body joined by dots. Verify the exact bytes received, not a re-encoded object.

signed = webhook-id + "." + webhook-timestamp + "." + raw_body
signature = base64(hmac_sha256(signed, base64_decode(secret_without_prefix)))

Reject a delivery whose timestamp is more than 300 seconds from your own clock. A signature stays valid forever once captured, and that window is what stops one being replayed at you later.

Two signing secrets can remain active during rotation. Add the new secret, confirm verification still succeeds, then retire the old secret.

Verifying a delivery

<?php

/**
 * Verify one Masar delivery.
 *
 * $body MUST be the raw request body, exactly as received. Decoding it to
 * an array and re-encoding produces different bytes — a space, a unicode
 * escape, a key order — and the signature will never match again.
 */
function masar_webhook_is_valid(string $body, array $headers, array $secrets): bool
{
    $id        = $headers['webhook-id'] ?? '';
    $timestamp = (int) ($headers['webhook-timestamp'] ?? 0);
    $offered   = $headers['webhook-signature'] ?? '';

    // Replay window first. A signature stays valid forever once captured.
    if ($timestamp <= 0 || abs(time() - $timestamp) > 300) {
        return false;
    }

    $signed = $id . '.' . $timestamp . '.' . $body;

    foreach (preg_split('/\s+/', trim($offered)) as $candidate) {
        foreach ($secrets as $secret) {
            $key = base64_decode(substr($secret, strlen('whsec_')), true) ?: $secret;
            $mine = 'v1,' . base64_encode(hash_hmac('sha256', $signed, $key, true));

            // hash_equals, never ===: a comparison that short-circuits leaks
            // the position of the first wrong byte.
            if (hash_equals($mine, $candidate)) {
                return true;
            }
        }
    }

    return false;
}

Events

One event is sent for each status change. A message moving from sent to delivered to read produces three separate events.

Create a key in the dashboard