POST/api/v2/messages/send
إرسال رسالة موحّدة
مسار الإرسال الوحيد لكل القنوات: SMS المحلي والدولي، واتساب الرسمي، واتساب ويب (بما فيه المجموعات الأصلية والصور)، بوت تلغرام، والبريد. `to` نص لمستلم واحد أو مصفوفة حتى 100 مستلم (دفعة رسمية). هيدر قوالب واتساب الرسمي يقبل الملف أو الرابط في نفس الطلب. HTTP 200 عند نجاح كل العناصر، و207 عند فشل جزئي في الدفعة. استخدم Idempotency-Key لإعادة المحاولة الآمنة.
مثال الطلب
صورة واتساب ويب
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","channel":"user_whatsapp_session","messageType":"free_text","content":{"text":"Product photo"},"attachment":{"type":"image","publicUrl":"https://cdn.example.com/catalog/sku-100.png","mimetype":"image/png","fileName":"sku-100.png"}}'مجموعة واتساب ويب الأصلية
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"120363012345678901@g.us","channel":"user_whatsapp_session","messageType":"free_text","content":{"text":"Hello group"},"conversationContext":{"moduleType":"whatsapp_web","accountId":"session-user-whatsapp-1","chatId":"120363012345678901@g.us"}}'مجموعة واتساب ويب مع صورة
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"120363012345678901@g.us","channel":"user_whatsapp_session","messageType":"free_text","content":{"text":"Catalog image"},"attachment":{"type":"image","publicUrl":"https://cdn.example.com/catalog/sku-100.png","mimetype":"image/png","fileName":"sku-100.png"},"conversationContext":{"moduleType":"whatsapp_web","accountId":"session-user-whatsapp-1","chatId":"120363012345678901@g.us"}}'مشترك بوت تلغرام
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"123456789","channel":"telegram_bot","messageType":"free_text","content":{"text":"Hello from the bot"},"conversationContext":{"moduleType":"telegram_bot","accountId":"6800abc123def4567890fedc","chatId":"123456789"}}'مشترك بوت تلغرام مع صورة
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"123456789","channel":"telegram_bot","messageType":"free_text","content":{"text":"Offer image"},"attachment":{"type":"image","publicUrl":"https://cdn.example.com/offers/banner.jpg","mimetype":"image/jpeg","fileName":"banner.jpg"},"conversationContext":{"moduleType":"telegram_bot","accountId":"6800abc123def4567890fedc","chatId":"123456789"}}'قالب واتساب تشغيلي مع هيدر ومتغيرات وزر رابط
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963911111111","messageType":"utility","channel":"official_whatsapp","template":{"key":"order_ready_notice","variablesIndexed":["أحمد","A-1042","25000"],"buttonVariables":[{"index":0,"subType":"url","text":"A-1042"}],"headerMediaUrl":"https://cdn.example.com/order-ready.jpg","headerMediaType":"image"}}'إرسال SMS محلي سريع
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Hello, this is a test message from Rasel."}}'قالب واتساب رسمي مع رابط الهيدر
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","channel":"official_whatsapp","messageType":"marketing","template":{"key":"bookingconfirmation6","language":"ar","variablesIndexed":["أحمد"],"headerMediaUrl":"https://cdn.example.com/booking.pdf","headerMediaType":"document"}}'رمز OTP مع اختيار القناة تلقائياً
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","messageType":"otp","channel":"auto","content":{"otpCode":"123456"},"sender":{"id":"6800abc123def4567890fedc"}}'رمز OTP من قالب
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","messageType":"otp","template":{"key":"verification_code","variablesIndexed":["123456"]}}'إرسال نص مختصر
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","text":"Hello"}'رسالة SMS محلية نص حر
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","messageType":"free_text","channel":"local_sms","content":{"text":"Hello, this is a sample API message"}}'قالب تشغيلي بمتغيرات مسماة
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","messageType":"utility","template":{"id":"64abc123...","variablesNamed":{"1":"Ahmed","2":"Order #456"}}}'قالب تسويقي على واتساب الرسمي
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963912345678","messageType":"marketing","channel":"official_whatsapp","template":{"key":"promo_offer","variablesIndexed":["50%","End of month"]}}'مشترك بوت تلغرام
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"123456789","channel":"telegram_bot","messageType":"free_text","content":{"text":"Hello from the bot"},"conversationContext":{"moduleType":"telegram_bot","accountId":"6800abc123def4567890fedc","chatId":"123456789"}}'مشترك بوت تلغرام مع صورة
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"123456789","channel":"telegram_bot","messageType":"free_text","content":{"text":"Offer image"},"attachment":{"type":"image","publicUrl":"https://cdn.example.com/offers/banner.jpg","mimetype":"image/jpeg","fileName":"banner.jpg"},"conversationContext":{"moduleType":"telegram_bot","accountId":"6800abc123def4567890fedc","chatId":"123456789"}}'قالب واتساب رسمي تشغيلي مع وسائط الهيدر
curl --location 'https://raselsms.com/api/v2/messages/send' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"to":"+963911111111","messageType":"utility","channel":"official_whatsapp","template":{"key":"order_ready_notice","variablesIndexed":["أحمد","A-1042","25000"],"buttonVariables":[{"index":0,"subType":"url","text":"A-1042"}],"headerMediaUrl":"https://cdn.example.com/order-ready.jpg","headerMediaType":"image"}}'طلب HTTP
POST /api/v2/messages/send
ترويسات الطلب
| الترويسة | النوع | الوصف |
|---|---|---|
| X-API-Key | string | مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. * |
| Idempotency-Key | string | مفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency. |
جسم الطلب
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| to | string | المستلم: رقم دولي E.164، أو بريد عندما تكون القناة email، أو معرّف مجموعة واتساب، أو معرّف محادثة تلغرام، أو مصفوفة نصوص حتى 100 مستلم للدفعة الرسمية. * | |
| text | string | اختصار يحوَّل إلى free_text مع اختيار القناة تلقائياً عندما لا يُرسل content.text. | |
| channel | auto | local_sms | int_sms | user_whatsapp_session | system_whatsapp_sessions | official_whatsapp | official_whatsapp_otp | telegram_otp | telegram_bot | email_user | قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها. | |
| messageType | otp | utility | marketing | free_text | تصنيف الرسالة: otp أو utility أو marketing أو free_text. | |
| content | object | في الإرسال الموحّد: كائن المحتوى (نص أو رمز OTP أو موضوع البريد). في القوالب: متن SMS أو الرسالة، أو HTML/نص البريد. | |
| attachment | object | وسائط صادرة لواتساب ويب وبووتات تلغرام. تلغرام يتطلب رابط HTTPS عاماً في publicUrl. | |
| conversationContext | object | مطلوب لـ telegram_bot. لمجموعات واتساب ويب ضع chatId على JID المجموعة الأصلية. accountId هو اسم الجلسة أو معرّف بوت تلغرام. | |
| template | object | مرجع القالب (id أو key) واللغة والمتغيرات وهيدر اختياري لهذا الإرسال. | |
| options | object | خيارات إرسال اختيارية مثل scheduleAt وidempotencyKey وبيانات العميل. | |
| sender | object | تجاوز اختياري للمرسل. إن حُذف يستخدم رسيل المرسل المعتمد الافتراضي ثم مرسل المنصة. | |
| officialSenderId | string | معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب. |
حقول الاستجابة
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| success | true | صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. | |
| requestId | string | معرّف طلب يولّده الخادم للتتبع والدعم. | |
| status | sent | queued | scheduled | حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. | |
| scheduledAt | string (date-time) | يظهر عندما تكون الحالة scheduled؛ وقت التسليم المؤجّل. | |
| resolved | object | القناة والمزوّد ومصدر المرسل بعد التوجيه. | |
| billing | object | التكلفة التقديرية والعملة لهذا الإرسال. | |
| tracking | object | معرّفات التتبع لدى المزوّد والداخلية، بما فيها التسليم لكل قناة عند التوزيع. |
رموز الحالة
| الحالة | الوصف |
|---|---|
| 200 | نجاح. |
| 202 | قُبل الطلب وأُضيف إلى الطابور. |
| 207 | اكتملت الدفعة بنجاح وفشل مختلط. |
| 400 | طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة. |
| 401 | مفتاح API مفقود أو غير صالح. |
| 402 | رصيد المحفظة أو حصة الباقة لا يكفي. |
| 403 | الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء. |
| 409 | تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة. |
| 429 | تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى. |
| 502 | فشل المزوّد الخارجي في معالجة الطلب. |
| 503 | المزوّد غير متاح أو انتهت مهلة الاتصال. |
جرّب الطلب
قد يخصم هذا الطلب من رصيد المحفظة أو حصة الباقة.
الاستجابة
نفّذ طلباً لعرض الاستجابة.