دليل واجهة WhatsApp API وWebhooks للمطورين | مسار

استخدم واجهة REST لإرسال الرسائل وإدارة البيانات من نظامك. تطبق الواجهة قواعد الحصص ورسوم الإدارة ومنع التكرار نفسها الموجودة في لوحة التحكم.

العنوان الأساسي: https://router.atyaf.co/api/v1

المصادقة

أرسل مفتاح API كرمز Bearer في كل طلب. يحدد المفتاح الحساب تلقائياً، لذلك لا ترسل معرّف الحساب. أي عنصر يخص حساباً آخر يعيد 404.

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

يبدأ مفتاح الإنتاج بـ msr_live_، ثم 48 حرفاً، ثم رمز تحقق من 6 أحرف. انسخه كاملاً كما يظهر عند الإنشاء.

يظهر المفتاح مرة واحدة عند الإنشاء، ولا يمكن استرجاعه لاحقاً. إذا فقدته، ألغِه وأنشئ مفتاحاً جديداً.

يمكن تقييد المفتاح بقائمة عناوين وتحديد تاريخ انتهاء له. كلاهما يُرفض عند المصادقة، قبل أي خصم.

الصلاحيات

كل مسار يطلب صلاحية واحدة. امنح المفتاح ما يحتاجه التكامل فقط. مفتاح التقارير الذي لا يملك صلاحية messages:send لا يستطيع الإرسال أو الإنفاق، لكنه قد يكشف بيانات حسابك. أبطل أي مفتاح يتسرّب فوراً وأنشئ بديلاً.

الأخطاء

تعيد كل استجابة فاشلة رمز خطأ ثابتاً داخل البنية نفسها. ابنِ منطق التكامل على الرمز، لا على نص الرسالة، لأن النص مترجم وقد يتغير.

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

كل استجابة تحمل ترويسة Masar-Request-Id، وتتكرّر داخل جسم الخطأ. اذكرها في طلب الدعم فتقودنا إلى طلب واحد بعينه في سجلّك.

حدود المعدّل

الحدود لكل مفتاح ولكل دقيقة، لا لكل عنوان IP — عميلان خلف اتصال مكتب واحد لا يتشاركان الحصة. كل استجابة تحمل X-RateLimit-Limit وX-RateLimit-Remaining، والرفض يحمل Retry-After.

منع التكرار

كل طلب كتابة ينفق مالاً أو لا يمكن التراجع عنه يحتاج ترويسة Idempotency-Key: ‏POST /v1/messages و POST /v1/campaigns وبدء الحملة وإيقافها واستئنافها وإلغاؤها. أي نص فريد يكفي، وUUID لكل طلب هو الخيار المعتاد.

تمنع هذه الترويسة تكرار الإرسال أو الحجز عندما يعيد نظامك الطلب بسبب انقطاع الاتصال.

• المفتاح نفسه بالمحتوى نفسه: يُعاد جواب الطلب الأول مع الترويسة Idempotent-Replayed: true، ولا يُرسل ولا يُخصم شيء ثانية.
• إذا استخدمت المفتاح نفسه مع محتوى مختلف، تعيد الواجهة 422 ورمز idempotency_conflict. استخدم مفتاحاً جديداً لكل عملية مختلفة.
• المفتاح نفسه والطلب الأول ما زال يُعالَج: 409 idempotency_in_flight. أعد المحاولة بعد لحظة.

تُؤخذ بصمة المحتوى على الرقم بعد التوحيد، فإعادة المحاولة بصيغة رقم مختلفة تُعيد الجواب بدل أن تتعارض.

المسارات

مواصفة OpenAPI

هذه الواجهة كاملة منشورة كمستند OpenAPI 3.1 على رابط ثابت. وجّه أي مولّد إليه لتحصل على عميل مكتوب بلغتك بدل عميل يدوي يتخلّف عن الواجهة مع الوقت.

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

يُعاد توليد المستند من المسارات المتاحة مع كل إصدار. تستخدم كل العمليات مصادقة Bearer، ولا تحتاج إلى إرسال معرّف الحساب.

إرسال رسالة

أرسل قالباً معتمداً إلى مستلم واحد. تعني الاستجابة 202 أن الرسالة دخلت الطابور؛ وتصل تحديثات التسليم عبر Webhook أو عند قراءة بيانات الرسالة.

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

تعني الاستجابة 202 أن مسار قبل الرسالة وأضافها إلى قائمة الإرسال. لا تعني أنها وصلت. تظهر النتيجة النهائية في حالة الرسالة أو عبر Webhook، وتُعاد رسوم الإدارة تلقائياً إذا لم تُرسل.

الردّ داخل محادثة

أرسل `text` بدل `template_id` للرد على شخص كتب إليك. لا تحتاج إلى قالب، ولا يخصم مسار رسوم إدارة لهذا الرد. تظهر أي تكلفة لدى ميتا في حساب أعمالك.

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

خلال 24 ساعة من آخر رسالة أرسلها لك ذلك الشخص فقط. وخارجها يُرفض الطلب بـ`service_window_closed` قبل أن يُخصم أي شيء، والقالب المعتمد هو الطريق.

الرسالة التي تصل ومعها صورة أو مستند تحمل معرّف وسائط. اجلب بياناتها عبر: 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');

Webhook

نرسل الأحداث موقّعة إلى رابطك عبر POST. التسليمات تتبع Standard Webhooks، فأي مكتبة متوافقة تتحقّق منها دون كود خاص.

ثلاث ترويسات ترافق كل تسليم:

التوقيع هو HMAC-SHA256 للمعرّف والطابع الزمني والجسم الخام، موصولة بنقاط. تحقّق من البايتات كما وصلتك، لا من كائن أعدت ترميزه.

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

ارفض أي تسليم يبعد طابعه الزمني أكثر من 300 ثانية عن ساعتك. التوقيع يبقى صالحاً إلى الأبد بعد التقاطه، وهذه النافذة هي ما يمنع إعادة إرساله إليك لاحقاً.

يمكن أن يكون مفتاحا توقيع فعّالان معاً أثناء التبديل. أضف المفتاح الجديد، وتأكد من نجاح التحقق، ثم ألغِ القديم.

التحقق من تسليم

<?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;
}

الأحداث

نرسل حدثاً واحداً لكل تغيير. انتقال الرسالة من «أُرسلت» إلى «وصلت» ثم «قُرئت» ينتج ثلاثة أحداث منفصلة.

أنشئ مفتاحاً من لوحة التحكم