POST/api/v2/messages/send
إرسال رسالة موحّدة
مسار الإرسال الوحيد لكل القنوات: SMS المحلي والدولي، واتساب الرسمي، واتساب ويب (بما فيه المجموعات الأصلية والصور)، بوت تلغرام، والبريد. `to` نص لمستلم واحد أو مصفوفة حتى 100 مستلم (دفعة رسمية). هيدر قوالب واتساب الرسمي يقبل الملف أو الرابط في نفس الطلب. HTTP 200 عند نجاح كل العناصر، و207 عند فشل جزئي في الدفعة. استخدم Idempotency-Key لإعادة المحاولة الآمنة.
متى تستخدمه. أي إرسال تشغيلي من نظامك. لدورات OTP ذات إرسال/إعادة إرسال/تحقق استخدم /api/v2/verification/*.
مثال الطلب
مثال صحيح: 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."}}'مثال صحيح: OTP مع اختيار قناة تلقائي
curl --location 'https://raselsms.com/api/v2/messages/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--header 'Idempotency-Key: otp-login-user-42-attempt-1' \--data '{"to":"+963912345678","channel":"auto","messageType":"otp","content":{"otpCode":"482193"}}'مثال صحيح: قالب واتساب رسمي مع متغيرات وزر رابط
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"}}'مثال صحيح: قالب واتساب رسمي مع ملف هيدر في نفس الطلب
curl --location 'https://raselsms.com/api/v2/messages/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: multipart/form-data' \--data '{"to":"+963912345678","channel":"official_whatsapp","messageType":"marketing","template":"{\"key\":\"bookingconfirmation6\",\"language\":\"ar\",\"variablesIndexed\":[\"أحمد\"]}","mediaType":"document","headerMedia":"<multipart binary PDF>","note":"Content-Type: multipart/form-data"}'مثال صحيح: صورة واتساب ويب
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":"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":["+963912345678","+963987654321"],"channel":"local_sms","messageType":"free_text","content":{"text":"Batch notice from Rasel."}}'مثال خاطئ: خطأ: بدون حقل to
curl --location 'https://raselsms.com/api/v2/messages/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"channel":"local_sms","content":{"text":"hi"}}'to إلزامي سواء كان نصاً أو مصفوفة.
مثال خاطئ: خطأ: بدون مفتاح API
curl --location 'https://raselsms.com/api/v2/messages/send' \--header 'Content-Type: application/json' \--data '{"to":"+963912345678","channel":"local_sms","messageType":"free_text","content":{"text":"Hello, this is a test message from Rasel."}}'المسار يرفض الطلب فوراً بدون X-API-Key.
مثال خاطئ: خطأ: تلغرام بلا conversationContext
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":"hi"}}'telegram_bot يتطلب moduleType وaccountId وchatId لمشترك ضغط /start.
مثال خاطئ: خطأ: رقم غير مسجّل في واتساب
curl --location 'https://raselsms.com/api/v2/messages/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"to":"+963900000000","channel":"official_whatsapp","messageType":"utility","template":{"key":"order_ready_notice","variablesIndexed":["أحمد"]}}'التحقق قبل الإرسال يمنع الفوترة على رقم غير مسجّل.
صورة واتساب ويب
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"}}'Matches POST /api/v2/templates order_ready_notice. variablesIndexed fills body {{1}} {{2}} {{3}}. buttonVariables[0].text is the URL-button suffix only.
إرسال 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"}}'مثال الاستجابة
200 — SMS محلي صحيح
{ "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent", "resolved": { "channel": "local_sms", "provider": "sms_mtn", "senderSource": "account_default" }, "billing": { "estimatedCost": 0.02, "currency": "USD" }, "tracking": { "messageId": "6800msg123def4567890aaaa", "usageId": "6800use123def4567890bbbb", "queueId": null }}200 — OTP مع اختيار قناة تلقائي
{ "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent", "resolved": { "channel": "int_sms", "provider": "sms_taqnyat", "senderSource": "account_default" }, "billing": { "estimatedCost": 0.02, "currency": "USD" }, "tracking": { "messageId": "6800msg123def4567890aaaa", "usageId": "6800use123def4567890bbbb", "queueId": null }}200 — قالب واتساب رسمي مع متغيرات وزر رابط
{ "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent", "resolved": { "channel": "official_whatsapp", "provider": "meta", "senderSource": "official_default" }, "billing": { "estimatedCost": 0.02, "currency": "USD" }, "tracking": { "messageId": "6800msg123def4567890aaaa", "usageId": "6800use123def4567890bbbb", "queueId": null }}200 — صورة واتساب ويب
{ "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent", "resolved": { "channel": "user_whatsapp_session", "provider": "user_whatsapp_session", "senderSource": "session" }, "billing": { "estimatedCost": 0.02, "currency": "USD" }, "tracking": { "messageId": "6800msg123def4567890aaaa", "usageId": "6800use123def4567890bbbb", "queueId": null }}200 — مشترك بوت تلغرام
{ "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent", "resolved": { "channel": "telegram_bot", "provider": "telegram_bot", "senderSource": "bot" }, "billing": { "estimatedCost": 0.02, "currency": "USD" }, "tracking": { "messageId": "6800msg123def4567890aaaa", "usageId": "6800use123def4567890bbbb", "queueId": null }}200 — دفعة رسمية لمستلمين
{ "success": true, "batch": true, "summary": { "total": 2, "sent": 2, "queued": 0, "failed": 0 }, "results": [ { "to": "+963912345678", "success": true, "requestId": "msgreq_1739012345678_abc123", "status": "sent" }, { "to": "+963987654321", "success": true, "requestId": "msgreq_1739012345678_def456", "status": "sent" } ]}400 — خطأ: بدون حقل to
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "VALIDATION_ERROR", "error": "to is required"}to إلزامي سواء كان نصاً أو مصفوفة.
401 — خطأ: بدون مفتاح API
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}المسار يرفض الطلب فوراً بدون X-API-Key.
400 — خطأ: تلغرام بلا conversationContext
{ "success": false, "code": "VALIDATION_ERROR", "error": "conversationContext is required for telegram_bot"}telegram_bot يتطلب moduleType وaccountId وchatId لمشترك ضغط /start.
400 — خطأ: رقم غير مسجّل في واتساب
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "WHATSAPP_NOT_REGISTERED", "error": "الرقم غير مسجل في واتساب"}التحقق قبل الإرسال يمنع الفوترة على رقم غير مسجّل.
402 — الرصيد أو حصة الباقة لا تكفي.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "INSUFFICIENT_BALANCE", "error": "Insufficient wallet or pool balance"}409 — تعارض Idempotency-Key أو المفتاح ما زال قيد المعالجة.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "IDEMPOTENCY_KEY_CONFLICT", "error": "The same Idempotency-Key was reused with a different body"}403 — الهاتف غير موثّق أو الصلاحية غير كافية (غالباً messages:create أو api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "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/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 | enum | قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها. | |
| messageType | enum | تصنيف الرسالة: otp أو utility أو marketing أو free_text. | |
| content | object | في الإرسال الموحّد: كائن المحتوى (نص أو رمز OTP أو موضوع البريد). في القوالب: متن SMS أو الرسالة، أو HTML/نص البريد. | |
| content.text | string | نص الرسالة. مع وسائط واتساب يكون هذا النص التعليق. | |
| content.otpCode | string | رمز التحقق عندما يكون نوع الرسالة otp ولا ترسل قالباً. | |
| content.subject | string | موضوع البريد عندما تكون القناة بريداً. | |
| attachment | object | ملف مرفق مع واتساب ويب أو بوت تلغرام. تلغرام يحتاج رابط HTTPS يمكن فتحه من الإنترنت في publicUrl. | |
| attachment.type | enum | نوع الوسيط: image أو video أو audio أو document. * | |
| attachment.publicUrl | string | رابط HTTPS عام يستطيع المزوّد تنزيله. مطلوب لوسائط بوت تلغرام. | |
| attachment.base64 | string | Base64 خام بلا بادئة data:. لواتساب ويب فقط. تلغرام يتجاهله. | |
| attachment.mimetype | string | نوع الملف، مثل image/png. | |
| attachment.fileName | string | اسم الملف الذي يراه المستلم، مثل sku-100.png. | |
| attachment.assetId | string | معرّف ملف وسائط مرفوع مسبقاً لهذا الحساب. | |
| conversationContext | object | مطلوب لـ telegram_bot. لمجموعات واتساب ويب ضع chatId على JID المجموعة الأصلية. accountId هو اسم الجلسة أو معرّف بوت تلغرام. | |
| conversationContext.moduleType | enum | whatsapp_web أو whatsapp_official أو telegram_bot. * | |
| conversationContext.accountId | string | اسم جلسة واتساب ويب، أو معرّف بوت تلغرام. * | |
| conversationContext.chatId | string | معرّف واتساب JID بما فيه groupId@g.us، أو معرّف محادثة تلغرام لمستخدم بدأ البوت. * | |
| conversationContext.contactId | string | معرّف جهة اتصال اختياري في راسل. | |
| conversationContext.conversationKey | string | مفتاح محادثة اختياري إذا كان لديك واحد. | |
| template | object | مرجع القالب (id أو key) واللغة والمتغيرات وهيدر اختياري لهذا الإرسال. | |
| template.id | string | معرّف القالب الداخلي من قائمة القوالب. | |
| template.key | string | اسم القالب أو مفتاحه، مثل order_ready_notice. | |
| template.language | string | لغة قالب ميتا مثل ar أو en. لا تُستخدم للـ SMS. | |
| template.variablesIndexed | string-list | متغيرات المتن بالترتيب: أول قيمة تملأ {{1}}. | |
| template.buttonVariables | json | لواحق أزرار الرابط، منفصلة عن متغيرات المتن. index هو ترتيب الزر بدءاً من 0. | |
| template.variablesNamed | json | متغيرات بأسمائها ككائن من نصوص. | |
| template.headerAssetId | string | معرّف وسائط هيدر مرفوعة مسبقاً. فضّل headerMediaUrl في نفس الطلب. | |
| template.headerMediaUrl | string | رابط عام لصورة أو فيديو أو مستند الهيدر لهذا الإرسال فقط. | |
| template.headerMediaType | enum | image أو video أو document. أرسله مع headerMediaUrl عندما لا يُستنتج النوع. | |
| template.header | string | رابط نصي مرادف لـ headerMediaUrl. لا ترسل كائناً. | |
| options | object | خيارات إرسال اختيارية مثل scheduleAt وidempotencyKey وبيانات العميل. | |
| options.priority | enum | مهمل ولا يُؤخذ به. الإرسال أصلاً بأولوية عالية. | |
| options.idempotencyKey | string | مفتاح إعادة محاولة اختياري. فضّل ترويسة Idempotency-Key. | |
| options.scheduleAt | string | وقت مستقبلي بصيغة ISO 8601. يتطلب خطة تسمح بالرسائل المجدولة. | |
| options.metadata | json | بياناتك الخاصة تُحفظ مع الرسالة. | |
| sender | object | تجاوز اختياري للمرسل. إن حُذف يستخدم راسل المرسل المعتمد الافتراضي ثم مرسل المنصة. | |
| sender.id | string | معرّف مرسل SMS المعتمد. احذفه لاستخدام المرسل الافتراضي. | |
| sender.name | string | اسم مرسل SMS المعتمد. بديل عن sender.id. | |
| sender.officialId | string | معرّف مرسل واتساب الرسمي. نفس officialSenderId. | |
| officialSenderId | string | معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب. |
حقول الاستجابة
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| success | enum | صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. | |
| requestId | string | معرّف طلب يولّده الخادم للتتبع والدعم. | |
| status | enum | حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. | |
| scheduledAt | string | يظهر عندما تكون الحالة scheduled؛ وقت التسليم المؤجّل. | |
| resolved | object | القناة والمزوّد ومصدر المرسل بعد التوجيه. | |
| resolved.channel | string | قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها. | |
| resolved.provider | string | فلتر أو قيمة مزوّد القالب: user_session أو meta أو internal. | |
| resolved.senderSource | string | كيف اختير المرسل: المعرّف الذي أرسلته، أو الافتراضي في الحساب، أو مرسل المنصة. | |
| resolved.channels | string-list | أسماء القنوات العامة عندما ينجح التوزيع على أكثر من قناة متوافقة. | |
| billing | object | التكلفة التقديرية والعملة لهذا الإرسال. | |
| billing.estimatedCost | number | السعر التقديري لهذا الإرسال قبل التسوية النهائية. | |
| billing.currency | string | رمز عملة estimatedCost حسب ISO، مثل USD. | |
| tracking | object | معرّفات التتبع لدى المزوّد والداخلية، بما فيها التسليم لكل قناة عند التوزيع. | |
| tracking.messageId | string | معرّف الرسالة في راسل لهذا الإرسال. | |
| tracking.usageId | string | معرّف سجل الاستهلاك لهذه الحركة. | |
| tracking.queueId | string | معرّف مهمة الطابور عندما يكون الإرسال في الانتظار أو مجدولاً. | |
| tracking.deliveries | json | تتبع لكل قناة عند تفعيل التوزيع. |
رموز الحالة
| الحالة | الوصف |
|---|---|
| 200 | نجاح. |
| 202 | قُبل الطلب وأُضيف إلى الطابور. |
| 207 | جزء من المستلمين وصلته الرسالة، وجزء فشل. |
| 400 | طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة. |
| 401 | مفتاح API مفقود أو غير صالح. |
| 402 | رصيد المحفظة أو حصة الباقة لا يكفي. |
| 403 | الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء. |
| 409 | تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة. |
| 429 | تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى. |
| 502 | فشل المزوّد الخارجي في معالجة الطلب. |
| 503 | المزوّد غير متاح أو انتهت مهلة الاتصال. |
حالات يجب أن تعرفها
- الحد الأقصى للدفعة 100 مستلم. الحقول المشتركة (القناة، النوع، المحتوى/القالب، المرسل) تُطبَّق على الجميع.
- batchRequests[] ما زال مقبولاً للتوافق لكنه مهمل؛ استخدم to[].
- اسحب accountId وchatId من واجهات سياق الإرسال قبل إرسال واتساب ويب أو تلغرام.
- لهيدر قوالب واتساب الرسمي أرسل الملف أو الرابط في نفس طلب /messages/send. إنشاء القالب يقبل headerMedia في نفس POST /api/v2/templates.
جرّب الطلب
قد يخصم هذا الطلب من رصيد المحفظة أو حصة الباقة.
لست مسجلاً، أو رفض الخادم هذه الجلسة. القوائم تبقى فارغة إلى أن تسجّل الدخول أو تكتب مفتاحاً صالحاً، ولن يظهر حساب شخص آخر.
مفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency.
اختر القناة، ثم الرقم، ثم نص الرسالة أو قالباً من حسابك. أسماء المرسلين والأرقام والقوالب تُؤخذ من حسابك إذا كان حقل المفتاح فارغاً، أو من صاحب المفتاح إذا كتبته.
المستلم بالصيغة الدولية، مثل +963912345678. للبريد أدخل العنوان.
وجهة التسليم. الحقول التالية تتغير حسب القناة.
اسم مرسل SMS المعتمد. اتركه فارغاً لاستخدام المرسل الافتراضي.
النص الحر رسالة عادية. رسائل الخدمة والتسويق تستخدم قالباً. رمز التحقق يمكن إرساله كرمز أو كقالب.
النص الذي يراه المستلم. مع وسائط واتساب يكون هذا النص التعليق.
الطلب
{ "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" }}الاستجابة
نفّذ طلباً لعرض الاستجابة.