توثيق الـ API

ادمج إرسال واتساب في تطبيقك بعدد بسيط من طلبات HTTP.

بداية سريعة
الرابط الأساسي
https://whatsapp.olspark.net
مُعرّف الـ instance الخاص بك (استخدمه في مسارات الـ endpoints)
your-instance-id
المفتاح العام (X-Api-Key)
olw_pub_xxxxxxxxxxxx
النطاق المقيّد
yourdomain.com
المفتاح السري بيظهر مرة واحدة فقط عند إنشاء المفتاح. احفظه في مكان آمن — لن يُعرض مرة أخرى.
1 المصادقة

أرسل المفتاح العام والمفتاح السري كـ headers في كل طلب.

X-Api-Key: olw_pub_xxxxxxxxxxxx
X-Api-Secret: olw_sec_your_secret_key

تقييد النطاق

كل مفتاح مرتبط بنطاق واحد. طلبات المتصفح تُتحقق عبر Origin/Referer، ولازم تطابق yourdomain.com. للطلبات من سيرفر لسيرفر (بدون Origin/Referer) أرسل الـ header X-Api-Domain: yourdomain.com

2 ربط رقم / الحصول على الـ QR

POST /api/instances/your-instance-id/connect

بيبدأ (أو يعيد استخدام) جلسة واتساب. لو الرقم لسه مش مربوط بيرجّع صورة QR — اعرضها لمستخدمك عشان يمسحها من واتساب ← الأجهزة المرتبطة.

cURL
curl -X POST "https://whatsapp.olspark.net/api/instances/your-instance-id/connect" \
  -H "X-Api-Key: olw_pub_xxxxxxxxxxxx" \
  -H "X-Api-Secret: olw_sec_your_secret_key" \
  -H "X-Api-Domain: yourdomain.com"
JavaScript — show the QR to your user
const r = await fetch("https://whatsapp.olspark.net/api/instances/your-instance-id/connect", {
  method: "POST",
  headers: { "X-Api-Key": "olw_pub_xxxxxxxxxxxx", "X-Api-Secret": "olw_sec_your_secret_key" }
});
const data = await r.json();
if (data.loggedIn) {
  // already connected
} else if (data.state === "AwaitingQr") {
  document.getElementById("qr").src = data.qrImage; // ready-to-use data URI
}
الاستجابة 200
{
  "instanceId": "your-instance-id",
  "state": "AwaitingQr",
  "loggedIn": false,
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "qrContentType": "image/png",
  "qrImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

الخطوات: نادِ connect ← لو الحالة AwaitingQr اعرض qrImage للمستخدم ← تابع endpoint الحالة لحد ما الحالة تبقى Ready.

3 حالة الاتصال

GET /api/instances/your-instance-id

اعرف إن كان الرقم متصل. تابعه بعد عرض الـ QR لحد ما loggedIn تبقى true.

curl "https://whatsapp.olspark.net/api/instances/your-instance-id" \
  -H "X-Api-Key: olw_pub_xxxxxxxxxxxx" -H "X-Api-Secret: olw_sec_your_secret_key" -H "X-Api-Domain: yourdomain.com"
// { "instanceId": "your-instance-id", "state": "Ready", "loggedIn": true }

الحالات: AwaitingQr · Loading · Ready · Disconnected · Failed

4 إرسال رسالة

POST /api/instances/your-instance-id/messages

يضيف الرسالة للطابور ويرجّع فوراً مُعرّف مهمة (jobId) تقدر تتابعه لمعرفة الحالة النهائية.

cURL
curl -X POST "https://whatsapp.olspark.net/api/instances/your-instance-id/messages" \
  -H "X-Api-Key: olw_pub_xxxxxxxxxxxx" \
  -H "X-Api-Secret: olw_sec_your_secret_key" \
  -H "X-Api-Domain: yourdomain.com" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"201001234567","message":"Hello from the API"}'
JavaScript (fetch)
await fetch("https://whatsapp.olspark.net/api/instances/your-instance-id/messages", {
  method: "POST",
  headers: {
    "X-Api-Key": "olw_pub_xxxxxxxxxxxx",
    "X-Api-Secret": "olw_sec_your_secret_key",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ phoneNumber: "201001234567", message: "Hello from the API" })
});
C# (HttpClient)
using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://whatsapp.olspark.net/api/instances/your-instance-id/messages");
req.Headers.Add("X-Api-Key", "olw_pub_xxxxxxxxxxxx");
req.Headers.Add("X-Api-Secret", "olw_sec_your_secret_key");
req.Headers.Add("X-Api-Domain", "yourdomain.com");
req.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
req.Content = new StringContent(
    "{\"phoneNumber\":\"201001234567\",\"message\":\"Hello\"}",
    System.Text.Encoding.UTF8, "application/json");
var res = await http.SendAsync(req);
جسم الطلب
الاسمالنوعالوصف
phoneNumberstringرقم المستلم، أرقام فقط مع كود الدولة (مثال: 201001234567).
messagestringنص الرسالة.
extraDelaySecondsint?ثوانٍ إضافية اختيارية للانتظار قبل الإرسال بعد وصول المهمة لمقدمة الطابور.
الاستجابة 202
{
  "jobId": 12345,
  "status": "Queued",
  "instanceId": "your-instance-id",
  "phoneNumber": "201001234567",
  "idempotencyKey": "7f992967-eabe-4dd4-85f8-c35ee18f58d6"
}
5 متابعة حالة الرسالة

GET /api/instances/your-instance-id/messages/{jobId}

تابع المهمة لمعرفة إن كانت في الطابور أو قيد الإرسال أو اكتملت.

curl "https://whatsapp.olspark.net/api/instances/your-instance-id/messages/12345" \
  -H "X-Api-Key: olw_pub_xxxxxxxxxxxx" -H "X-Api-Secret: olw_sec_your_secret_key" -H "X-Api-Domain: yourdomain.com"

الحالات الممكنة: Queued · Running · Succeeded · Failed · OutcomeUnknown

6 منع التكرار (Idempotency)

أرسل header اسمه Idempotency-Key بقيمة فريدة (GUID) لكل رسالة. إعادة المحاولة بنفس المفتاح لا تُرسل رسالة مكررة — آمن مع الـ timeouts وإعادة المحاولة.

7 حدود المعدل والحصة
  • حد لكل ثانية: عدد الطلبات/الثانية في باقتك (أو تجاوز خاص بالمفتاح). التجاوز يرجّع 429.
  • الحصة الشهرية: عدد الرسائل/الشهر في باقتك. التجاوز يرجّع 402.
  • تقييد النطاق: أي طلب من نطاق غير المسجّل يرجّع 403.
8 أكواد الأخطاء
HTTPresultالوصف
401InvalidKeyمفتاح/سر API مفقود أو غير صحيح.
403DomainMismatch / Blockedمصدر الطلب لا يطابق نطاق المفتاح، أو المفتاح/الحساب محظور.
402QuotaExceeded / SubscriptionInactiveلا يوجد اشتراك نشط، أو انتهت الحصة الشهرية.
429RateLimitedتجاوزت حد المعدل — قلّل السرعة وأعد المحاولة.
400ValidationFailedرقم هاتف أو رسالة غير صحيحة.
404NotFoundالـ instance أو المهمة غير موجودة لهذا المفتاح.