توثيق الـ API
ادمج إرسال واتساب في تطبيقك بعدد بسيط من طلبات HTTP.
بداية سريعة
https://whatsapp.olspark.netyour-instance-idolw_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 -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"}'
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" })
});
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);
| الاسم | النوع | الوصف |
|---|---|---|
phoneNumber | string | رقم المستلم، أرقام فقط مع كود الدولة (مثال: 201001234567). |
message | string | نص الرسالة. |
extraDelaySeconds | int? | ثوانٍ إضافية اختيارية للانتظار قبل الإرسال بعد وصول المهمة لمقدمة الطابور. |
{
"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 أكواد الأخطاء
| HTTP | result | الوصف |
|---|---|---|
| 401 | InvalidKey | مفتاح/سر API مفقود أو غير صحيح. |
| 403 | DomainMismatch / Blocked | مصدر الطلب لا يطابق نطاق المفتاح، أو المفتاح/الحساب محظور. |
| 402 | QuotaExceeded / SubscriptionInactive | لا يوجد اشتراك نشط، أو انتهت الحصة الشهرية. |
| 429 | RateLimited | تجاوزت حد المعدل — قلّل السرعة وأعد المحاولة. |
| 400 | ValidationFailed | رقم هاتف أو رسالة غير صحيحة. |
| 404 | NotFound | الـ instance أو المهمة غير موجودة لهذا المفتاح. |