Rasel / Docs
AR
POST/api/v2/messages/bulk

وضع إرسال جماعي في الطابور

يخزّن مصفوفة رسائل، كل عنصر مستلم واحد وبنفس حقول POST /api/v2/messages/send. الرد 202 والحالة validating. لا يبدأ الإرسال قبل نجاح كل الصفوف. messagesPerSecond عدد صحيح من 1 إلى 10 وهو سقف مشترك لمهام الحساب حسب ترتيب إنشائها. لا يوجد حد منتج لعدد العناصر. Idempotency-Key إلزامي وبحد 200 حرفاً. نفس المفتاح ونفس name وmessagesPerSecond وmessages يعيد المهمة الحالية حتى لو اختلف ترتيب مفاتيح JSON. نفس المفتاح مع جسم مختلف يعيد 409. الحقول خارج هذه الثلاثة تُتجاهل. scheduleAt مرفوض لاحقاً للمهمة كلها. تكرار المستلم مسموح. صف واحد غير صالح يرفض المهمة بلا إرسال. الاشتراك غير النشط يرفض الطلب قبل إنشاء مهمة.

متى تستخدمه. عشرات أو آلاف الرسائل المختلفة دون انتظار الإرسال داخل الطلب. للإرسال المفرد أو دفعة حتى 100 مستلم بنفس النص استخدم POST /api/v2/messages/send.

مثال الطلب

مثال صحيح: صحيح: رسالتان

curl --location 'https://raselsms.com/api/v2/messages/bulk' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--header 'Idempotency-Key: bulk-example-001' \--data '{"name":"Morning notices","messagesPerSecond":10,"messages":[{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Example notice from Rasel."}},{"to":"+963987654321","channel":"local_sms","messageType":"free_text","content":{"text":"Example notice from Rasel."}}]}'

المفتاح موجود والسرعة ضمن السقف والمصفوفة غير فارغة.

مثال خاطئ: خطأ: المفتاح مفقود

curl --location 'https://raselsms.com/api/v2/messages/bulk' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"messagesPerSecond":10,"messages":[{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Example notice from Rasel."}}]}'

Idempotency-Key إلزامي.

مثال خاطئ: خطأ: سرعة أعلى من السقف

curl --location 'https://raselsms.com/api/v2/messages/bulk' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--header 'Idempotency-Key: bulk-example-002' \--data '{"messagesPerSecond":11,"messages":[{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Example notice from Rasel."}}]}'

القيمة لا تُخفَّض تلقائياً.

مثال خاطئ: خطأ: نفس المفتاح وجسم مختلف

curl --location 'https://raselsms.com/api/v2/messages/bulk' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--header 'Idempotency-Key: bulk-example-001' \--data '{"messagesPerSecond":5,"messages":[{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Example notice from Rasel."}}]}'

مثال الاستجابة

202 — صحيح: رسالتان

{  "success": true,  "id": "64b0c0ff0000000000000001",  "name": "Morning notices",  "status": "validating",  "messagesPerSecond": 10,  "pauseReason": null,  "total": 2,  "validatedCount": 0,  "counts": {    "pending": 0,    "sent": 0,    "failed": 0,    "cancelled": 0  },  "errorCode": null,  "errorMessage": null,  "createdAt": "2026-09-24T12:00:00.000Z"}

المفتاح موجود والسرعة ضمن السقف والمصفوفة غير فارغة.

400 — خطأ: المفتاح مفقود

{  "success": false,  "code": "IDEMPOTENCY_KEY_REQUIRED",  "error": "Idempotency-Key is required"}

Idempotency-Key إلزامي.

400 — خطأ: سرعة أعلى من السقف

{  "success": false,  "code": "MESSAGES_PER_SECOND_INVALID",  "error": "messagesPerSecond must be an integer from 1 to 10"}

القيمة لا تُخفَّض تلقائياً.

409 — خطأ: نفس المفتاح وجسم مختلف

{  "success": false,  "code": "IDEMPOTENCY_CONFLICT",  "error": "Idempotency key was used with a different body"}

400 — جسم أو سرعة أو مفتاح غير صالح. الرموز: IDEMPOTENCY_KEY_REQUIRED وIDEMPOTENCY_KEY_INVALID وINVALID_REQUEST_BODY وMESSAGES_PER_SECOND_INVALID وMESSAGES_REQUIRED وINVALID_MESSAGE. الرمز MESSAGES_REQUIRED.

{  "success": false,  "code": "MESSAGES_REQUIRED",  "error": "messages must be a non-empty array"}

403 — الاشتراك غير نشط قبل إنشاء أي مهمة. قد يكون 403 أيضاً FORBIDDEN عند نقص الصلاحية. الرمز SUBSCRIPTION_INACTIVE.

{  "success": false,  "code": "SUBSCRIPTION_INACTIVE",  "error": "Subscription is inactive"}

401 — مفتاح API مفقود أو غير صالح.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — الهاتف غير موثّق أو تنقص صلاحية messages:create. الرمز FORBIDDEN.

{  "success": false,  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

طلب HTTP

POST /api/v2/messages/bulk

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

الترويسةالنوعالوصف
X-API-Keystringمفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. *
Idempotency-Keystringمفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency. *

جسم الطلب

الحقلالنوعالوصفمثال
namestringالاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار.
messagesPerSecondintegerعدد صحيح من 1 إلى 10. الصفر والكسور وما فوق 10 ترفض الطلب. *
messagesjsonمصفوفة غير فارغة. كل عنصر كائن لمستلم واحد: to وchannel وmessageType وcontent وsender وtemplate وattachment حسب قواعد الإرسال المفرد. لا تستخدم مصفوفة داخل to ولا scheduleAt. *

رموز الحالة

الحالةالوصف
202قُبل الطلب وأُضيف إلى الطابور.
400طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة.
401مفتاح API مفقود أو غير صالح.
403الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء.
409تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة.
429تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى.

حالات يجب أن تعرفها

  • accepting: التخزين لم يكتمل ولن يُرسَل شيء. إن توقف التخزين تصبح المهمة rejected بالرمز INTAKE_INCOMPLETE.
  • validating: يُفحص كل صف. validatedCount يوضح التقدم. لا إرسال في هذه الحالة.
  • rejected: لم يُرسَل شيء. errorCode هو VALIDATION_FAILED أو INSUFFICIENT_BALANCE أو INTAKE_INCOMPLETE.
  • queued: مقبولة وتنتظر دور الإرسال. running: الإرسال جارٍ.
  • paused: الإرسال متوقف. pauseReason هو insufficient_balance أو provider_rate_limit أو user.
  • completed: انتهت المهمة حتى لو فشل بعض الصفوف. العدّادات تبقى منفصلة.
  • cancelled: الصفوف التي لم تُرسَل أصبحت cancelled. النافذة الحالية قد تكمل بضع إرسالات بعد طلب الإيقاف أو الإلغاء.

جرّب الطلب

قد يخصم هذا الطلب من رصيد المحفظة أو حصة الباقة.

المتغيرات

مفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency.

الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار.

عدد صحيح من 1 إلى 10. الصفر والكسور وما فوق 10 ترفض الطلب.

مصفوفة غير فارغة. كل عنصر كائن لمستلم واحد: to وchannel وmessageType وcontent وsender وtemplate وattachment حسب قواعد الإرسال المفرد. لا تستخدم مصفوفة داخل to ولا scheduleAt.

الطلب

{  "name": "Morning notices",  "messagesPerSecond": 10,  "messages": [    {      "to": "+963912345678",      "channel": "local_sms",      "messageType": "free_text",      "content": {        "text": "Example notice from Rasel."      }    },    {      "to": "+963987654321",      "channel": "local_sms",      "messageType": "free_text",      "content": {        "text": "Example notice from Rasel."      }    }  ]}

الاستجابة

نفّذ طلباً لعرض الاستجابة.