Masar API reference

Send WhatsApp templates from your own system.

العربية

One REST API over the same engine the console uses. There is no second path to a recipient: the charge, the quota, the idempotency claim and the delivery lease are identical whether a message is sent from a screen or from your code.

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

Authentication

Send your key as a bearer token on every request. The key identifies the account — no endpoint takes an account id, and a resource belonging to another account answers 404.

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

A key reads msr_live_ followed by 48 characters and a 6-character checksum. Underscores, never hyphens: an underscore is not a Base64 character, so a random hash can never be mistaken for a credential.

The key is shown once, at creation, and stored only as a SHA-256 hash. It cannot be recovered — if it is lost, revoke it and create another.

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 names one scope. Grant a key only what its integration needs — a reporting key without messages:send cannot spend your balance, so leaking it is not an emergency.

Errors

Every failure answers with the same envelope and a stable code. Branch on the code, never on the HTTP status or the message: two refusals often share a status and have opposite remedies, and the message text is translated and may be rewritten.

{
  "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.

Reads and writes other than sending	600 per minute
POST /v1/messages	120 per minute

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.

It is required rather than optional because a duplicate charge has a refund and a duplicate WhatsApp template has a reported number — and a number's quality rating does not recover.

• Same key, same payload: the first call's answer is replayed with Idempotent-Replayed: true, and nothing is sent or charged again.
• Same key, different payload: 422 idempotency_conflict. This catches the common bug of generating one key and reusing it across a loop — replaying silently would mean every recipient after the first hears nothing while the API keeps answering 200.
• 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 the live routes on every release, so an endpoint that exists is described and one that is described exists. Authentication is bearer auth on every operation; no endpoint takes 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 means charged and queued, not delivered. The wallet is debited before the send, because a charge for a message that never went out is fixed by a refund while a message sent and charged to nobody is fixed by nothing.

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:

webhook-id	msg_…
webhook-timestamp	1767225600
webhook-signature	v1,<base64> v1,<base64>

The signature is an HMAC-SHA256 over the id, the timestamp and the raw body joined by dots — verify against the exact bytes you received, never against 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 secrets can be live at once. During a rotation the signature header carries one signature per secret, space-separated, and a delivery is valid if any of them matches — so you can add the new secret, watch deliveries keep verifying, and retire the old one on your own clock.

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

Each event fires once per fact. A status that moves from sent to delivered to read is three deliveries, and a receipt the provider sends us twice is still one.

Event	When it fires
message.accepted	Charged and queued. Fires for a single send through the API and for every campaign recipient; an idempotent replay produces no second event.
message.sent	Handed to WhatsApp and accepted by it. The provider message id exists from here on.
message.delivered	The recipient device acknowledged it.
message.read	The recipient opened it. Only for recipients who have read receipts switched on.
message.failed	It will not arrive, and any charge has been handed back. Fires whether the provider refused the send outright, reported the failure afterwards, or we gave up on it.
template.approved	The template may now be sent. Fires whether the verdict arrived by webhook from Meta or was found by our catalogue reconciliation.
template.rejected	The template will not be sent, and the body carries the reason. Our own review refusing it counts as a rejection.
channel.quality_changed	The quality rating or messaging tier Meta holds for one of your numbers moved. The body is the number as it is now.
wallet.low_balance	The wallet is below your auto-recharge threshold, or below what you spent last week, with the day it reaches nothing at the current rate. At most once a day.

Create a key in the console