تخطَّ إلى المحتوى الرئيسي

SMS: الإرسال

إرسال رسالة أو أكثر عبر SMS باستخدام واجهة برمجة تطبيقات Mersal.

3 دقيقة قراءة

أرسل رسالة SMS واحدة أو أكثر في طلب واحد. مرّر عدة عناصر في مصفوفة contact لتنفيذ إرسال جماعي، مع إمكانية جدولة كل رسالة لوقت لاحق أو استهداف بوابة إرسال محددة.

النقطة الطرفية

POSThttps://mersal.it/api/sms/send

المصادقة

يتطلب مفتاح API الشخصي الخاص بك عبر ترويسة Api-key (أو بديل api_key في معامل الرابط/نص الطلب). راجع المصادقة.

معاملات الطلب

الاسمالنوعمطلوبالوصف
contactarrayنعممصفوفة المستلمين. يجب أن تحتوي على عنصر واحد على الأقل.
contact.*.numberstringنعمرقم هاتف المستلم.
contact.*.messagestringنعمنص رسالة SMS.
contact.*.gateway_identifierstringلامعرّف UID لبوابة SMS محددة للإرسال عبرها. احذف هذا الحقل لاستخدام بوابة SMS الافتراضية/النشطة في حسابك. مرّر معرّف بوابة محدد لفرض استخدامها — مثلاً لتوجيه الرسالة عبر Android SIM Gateway بدلاً من مزود SMS API.
contact.*.schedule_atstringلاجدولة التسليم لوقت لاحق، بصيغة Y-m-d H:i:s. احذف هذا الحقل للإرسال الفوري.

مثال على الطلب

curl -X POST https://mersal.it/api/sms/send \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": [
      {
        "number": "+201234567890",
        "message": "Your order has shipped!"
      },
      {
        "number": "+201098765432",
        "message": "Reminder: your appointment is tomorrow at 10am.",
        "schedule_at": "2026-08-01 10:00:00"
      }
    ]
  }'

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

{
  "success": true,
  "message": "SMS queued successfully",
  "data": {
    "contact": [
      {
        "number": "+201234567890",
        "status": "queued"
      },
      {
        "number": "+201098765432",
        "status": "scheduled"
      }
    ]
  }
}

عند فشل التحقق من صحة البيانات، تُرجع Mersal الحالة 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.number": ["The contact.0.number field is required."]
  }
}

جدولة الرسائل

حقل schedule_at يقبل التوقيت بصيغة Y-m-d H:i:s بتوقيت حسابك. الرسائل المجدولة تظهر بحالة scheduled في الاستجابة وتقدر تتابعها من لوحة التحكم أو عبر GET /api/get/sms.

الأخطاء

أكثر حالات الفشل شيوعًا هي مفتاح API مفقود أو غير صالح، أو اشتراك منتهي الصلاحية، أو خطأ تحقق 422 في مصفوفة contact. راجع الأخطاء ورموز الحالة للمرجع الكامل.

هل ساعدتك هذه الصفحة؟
SMS: الإرسال · شروحات مرسال