توثيق الـ 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 إرسال رسالة

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"
}
3 متابعة حالة الرسالة

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

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

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

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