للمطورين

واجهة برمجية بسيطة وموثوقية.

REST · V1 waaraby.com/api/v1

المصادقة

أنشئ مفاتيحك من لوحة التحكم. المفتاح يُعرض مرة واحدة ويُحفظ مشفراً. أرسل ترويسة Idempotency-Key مع كل طلب إرسال حتى لا تتكرر الرسالة عند إعادة المحاولة.

ترويسات الطلب

Authorization: Bearer <api_key>
Idempotency-Key: <unique-per-request>

نقاط الاتصال

POST /api/v1/messages/text

إرسال رسالة نصية إلى رقم أو مجموعة.

المعلمة	النوع	مطلوبة	الإعدادات
`wa_number_id`	integer	مطلوب	رقم الإرسال (من حسابك)
`to`	string	مطلوب	الرقم بصيغة دولية أو JID للمجموعة
`text`	string	مطلوب	نص الرسالة
`reply_to`	string	اختياري	معرّف رسالة للرد عليها (اقتباس)

curl -X POST https://waaraby.com/api/v1/messages/text \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"wa_number_id":1,"to":"value","text":"Hello from the API","reply_to":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/messages/text', {
    "wa_number_id": 1,
    "to": "value",
    "text": "Hello from the API",
    "reply_to": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/messages/text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"wa_number_id":1,"to":"value","text":"Hello from the API","reply_to":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/messages/text',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "wa_number_id": 1,
    "to": "value",
    "text": "Hello from the API",
    "reply_to": "value"
},
)
data = res.json()['data']

POST /api/v1/messages/media

إرسال صورة أو فيديو أو ملف أو رسالة صوتية.

المعلمة	النوع	مطلوبة	الإعدادات
`wa_number_id`	integer	مطلوب	رقم الإرسال
`to`	string	مطلوب	المستلم
`type`	string	مطلوب	image \| video \| file \| audio
`file_url`	string	مطلوب	رابط الملف (يُحمَّل بأمان)
`caption`	string	اختياري	تعليق على الملف

curl -X POST https://waaraby.com/api/v1/messages/media \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"wa_number_id":1,"to":"value","type":"value","file_url":"value","caption":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/messages/media', {
    "wa_number_id": 1,
    "to": "value",
    "type": "value",
    "file_url": "value",
    "caption": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/messages/media', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"wa_number_id":1,"to":"value","type":"value","file_url":"value","caption":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/messages/media',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "wa_number_id": 1,
    "to": "value",
    "type": "value",
    "file_url": "value",
    "caption": "value"
},
)
data = res.json()['data']

POST /api/v1/messages/poll

إرسال استطلاع رأي بخيارات.

المعلمة	النوع	مطلوبة	الإعدادات
`wa_number_id`	integer	مطلوب	رقم الإرسال
`to`	string	مطلوب	المستلم
`question`	string	مطلوب	سؤال الاستطلاع
`options`	string[]	مطلوب	الخيارات

curl -X POST https://waaraby.com/api/v1/messages/poll \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"wa_number_id":1,"to":"value","question":"value","options":["Option 1","Option 2"]}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/messages/poll', {
    "wa_number_id": 1,
    "to": "value",
    "question": "value",
    "options": [
        "Option 1",
        "Option 2"
    ]
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/messages/poll', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"wa_number_id":1,"to":"value","question":"value","options":["Option 1","Option 2"]}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/messages/poll',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "wa_number_id": 1,
    "to": "value",
    "question": "value",
    "options": [
        "Option 1",
        "Option 2"
    ]
},
)
data = res.json()['data']

POST /api/v1/messages/location

إرسال موقع جغرافي.

المعلمة	النوع	مطلوبة	الإعدادات
`wa_number_id`	integer	مطلوب	رقم الإرسال
`to`	string	مطلوب	المستلم
`latitude`	number	مطلوب	خط العرض
`longitude`	number	مطلوب	خط الطول

curl -X POST https://waaraby.com/api/v1/messages/location \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"wa_number_id":1,"to":"value","latitude":30.04,"longitude":30.04}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/messages/location', {
    "wa_number_id": 1,
    "to": "value",
    "latitude": 30.04,
    "longitude": 30.04
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/messages/location', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"wa_number_id":1,"to":"value","latitude":30.04,"longitude":30.04}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/messages/location',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "wa_number_id": 1,
    "to": "value",
    "latitude": 30.04,
    "longitude": 30.04
},
)
data = res.json()['data']

GET /api/v1/messages/{id}

حالة رسالة: مرسلة، مسلّمة، مقروءة، فاشلة.

المعلمة	النوع	مطلوبة	الإعدادات
`id`	string	مطلوب	معرّف الرسالة

curl -X POST https://waaraby.com/api/v1/messages/{id} \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"id":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/messages/{id}', {
    "id": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/messages/{id}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"id":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/messages/{id}',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "id": "value"
},
)
data = res.json()['data']

GET /api/v1/numbers

قائمة أرقامك وحالتها.

curl -X POST https://waaraby.com/api/v1/numbers \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '[]'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/numbers', []);

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/numbers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify([]),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/numbers',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json=[],
)
data = res.json()['data']

GET /api/v1/contacts

قائمة جهات الاتصال (مع ترقيم صفحات).

المعلمة	النوع	مطلوبة	الإعدادات
`page`	integer	اختياري	رقم الصفحة
`q`	string	اختياري	بحث بالاسم أو الرقم

curl -X POST https://waaraby.com/api/v1/contacts \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"page":1,"q":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/contacts', {
    "page": 1,
    "q": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"page":1,"q":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/contacts',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "page": 1,
    "q": "value"
},
)
data = res.json()['data']

POST /api/v1/contacts

إضافة جهة اتصال.

المعلمة	النوع	مطلوبة	الإعدادات
`name`	string	مطلوب	الاسم
`phone`	string	مطلوب	الرقم بصيغة دولية
`tags`	string[]	اختياري	وسوم

curl -X POST https://waaraby.com/api/v1/contacts \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"name":"value","phone":"value","tags":["Option 1","Option 2"]}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/contacts', {
    "name": "value",
    "phone": "value",
    "tags": [
        "Option 1",
        "Option 2"
    ]
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"name":"value","phone":"value","tags":["Option 1","Option 2"]}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/contacts',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "name": "value",
    "phone": "value",
    "tags": [
        "Option 1",
        "Option 2"
    ]
},
)
data = res.json()['data']

POST /api/v1/contacts/opt-out

تسجيل إلغاء اشتراك جهة اتصال (لن تتلقى حملات بعد الآن).

المعلمة	النوع	مطلوبة	الإعدادات
`phone`	string	مطلوب	الرقم

curl -X POST https://waaraby.com/api/v1/contacts/opt-out \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/contacts/opt-out', {
    "phone": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/contacts/opt-out', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"phone":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/contacts/opt-out',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "phone": "value"
},
)
data = res.json()['data']

GET /api/v1/chats

قائمة المحادثات مع آخر رسالة.

curl -X POST https://waaraby.com/api/v1/chats \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '[]'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/chats', []);

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/chats', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify([]),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/chats',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json=[],
)
data = res.json()['data']

GET /api/v1/chats/{jid}/messages

رسائل محادثة محددة.

المعلمة	النوع	مطلوبة	الإعدادات
`jid`	string	مطلوب	معرّف المحادثة

curl -X POST https://waaraby.com/api/v1/chats/{jid}/messages \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"jid":"value"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/chats/{jid}/messages', {
    "jid": "value"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/chats/{jid}/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"jid":"value"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/chats/{jid}/messages',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "jid": "value"
},
)
data = res.json()['data']

POST /api/v1/campaigns

إنشاء حملة رسائل لقائمة جهات اتصال.

المعلمة	النوع	مطلوبة	الإعدادات
`wa_number_id`	integer	مطلوب	رقم الإرسال
`list_id`	integer	مطلوب	قائمة جهات الاتصال
`message`	string	مطلوب	نص الرسالة (بدعم المتغيرات)

curl -X POST https://waaraby.com/api/v1/campaigns \
  -H 'Authorization: Bearer wa_live_xxx' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4' \
  -H 'Content-Type: application/json' \
  -d '{"wa_number_id":1,"list_id":1,"message":"Hello from the API"}'

$response = Http::withHeaders([
    'Authorization' => 'Bearer wa_live_xxx',
    'Idempotency-Key' => $idempotencyKey,
])->post('https://waaraby.com/api/v1/campaigns', {
    "wa_number_id": 1,
    "list_id": 1,
    "message": "Hello from the API"
});

$data = $response->json('data');

const res = await fetch('https://waaraby.com/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wa_live_xxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"wa_number_id":1,"list_id":1,"message":"Hello from the API"}),
});
const { data } = await res.json();

import requests, uuid

res = requests.post(
    'https://waaraby.com/api/v1/campaigns',
    headers={
        'Authorization': 'Bearer wa_live_xxx',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
    "wa_number_id": 1,
    "list_id": 1,
    "message": "Hello from the API"
},
)
data = res.json()['data']

إشعارات الويب هوك

استقبل الأحداث في نظامك فور وقوعها: رسائل واردة، تحديثات حالة، إلغاء اشتراكات، انقطاع أرقام، وحملات مكتملة.

الحدث	الإعدادات
`message.received`	رسالة واردة من عميل
`message.status`	تحديث حالة رسالة مُرسلة
`contact.opted_out`	إلغاء اشتراك جهة اتصال
`number.disconnected`	انقطاع رقم عن الخدمة
`campaign.finished`	اكتمال حملة

التحقق من التوقيع

كل إشعار ويب هوك يُوقَّع بـ HMAC-SHA256 للمجسم الخام باستخدام سر الويب هوك الخاص بحسابك. تحقق منه بمقارنة ثابتة الزمن.

مثال تحقق

X-Waaraby-Signature: sha256=<hex>

// PHP
$expected = hash_hmac('sha256', $rawBody, $webhookSecret);
if (! hash_equals($expected, $receivedSignature)) {
    abort(401);
}

أكواد الأخطاء

الكود	الإعدادات
400	طلب غير صالح — تحقق من المعلمات
401	مفتاح غير صالح أو منتهي
403	المفتاح لا يملك الصلاحية لهذا الإجراء
404	العنصر غير موجود
409	تعارض — نفس Idempotency-Key بمحتوى مختلف
422	بيانات غير مكتملة أو غير صحيحة
429	تجاوزت حد الطلبات — تحقق من ترويسة Retry-After

حدود المعدل

٦٠ طلباً في الدقيقة لكل مفتاح، و١٠ طلبات إرسال في الدقيقة. الحدود قابلة للتعديل من الإدارة.