إرسال رسائل SMS ورسائل MMS المدعومة

قبل الإرسال

أرسل رسالة SMS أو رسالة MMS مدعومة باستخدام رقم إرسال مُعدّ لحسابك. هذه عملية فعلية في بيئة الإنتاج قد تتواصل مع المستلمين وتترتب عليها رسوم. اقتصر على المستلمين المصرّح بمراسلتهم وحركة الرسائل المعتمدة؛ فالأرقام والقيمة المرجعية في المثال أدناه افتراضية.

يحتاج حسابك إلى موافقة لإرسال الرسائل الصادرة، وإلى الأذونات المنطبقة على المرسل والبلد وحركة الرسائل. بيانات اعتماد المستخدم المباشرة للحسابات الشخصية أو حسابات المستهلكين غير مؤهلة لاستخدام واجهة API هذه. ولبيانات الاعتماد المعتمدة والمخصصة لواجهة API مسار أهلية منفصل؛ وقد يحتاج مرسلو رسائل P2P عبر الجوال إلى أذونات إضافية لـ P2P وللولايات المتحدة وكندا. تأكد من إعداد الحساب الصحيح مع MultiTEL، ولا تعتبر امتلاك بيانات اعتماد API إذنًا تلقائيًا لإرسال أي حركة رسائل.

طلب الإرسال

نفّذ المصادقة عبر HTTPS باستخدام حساب API مفعّل ومن عنوان IP المصدر المسموح له. احتفظ ببيانات الاعتماد في مخزن للأسرار على جانب الخادم. استخدم POST مع حقول مرمّزة بصيغة النماذج، أو كائن JSON عند عدم تقديم أي حقول نموذج أو استعلام. لا تضع بيانات الاعتماد أو نص الرسالة في عنوان URL.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

عند استخدام مصفوفة JSON، ضع مصفوفة فعلية في to؛ ولا تضع سلسلة نصية تمثل مصفوفة JSON داخل حقل نموذج. اجعل الإرسال إلى مستلم واحد اختبار التكامل الأولي. يختلف دعم الإرسال الجماعي وMMS باختلاف المسار، لذا تأكد من دعمهما بالشكل المطلوب قبل استخدامهما.

اقرأ النتيجة كاملة

هذه حقول مختارة للتوضيح فقط؛ والتكلفة المعروضة ليست عرض سعر.

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

افحص حالة HTTP وقيمة status.code في JSON وقيمتي status/message في الاستجابة معًا. قد تكون رموز النتائج سلاسل نصية. احتفظ بقيمة sms_log_id_ori وقيم الرسالة والمرجع المُعادة لربط المعلومات عند طلب الدعم. تختلف قيمتا uniqueid وpid في النظام القديم باختلاف المسار؛ فلا تستنتج تنسيقهما أو تفترض أنهما رمزان لمنع تكرار تنفيذ طلبات العميل.

تشير Success أو Message queued عادةً إلى قبول الرسالة من المسار المحدد، وليس إلى وصولها إلى هاتف الشخص. وحالة إشعار الاستدعاء الراجع الأولي، مثل sent، لا تثبت بمفردها التسليم النهائي.

أجزاء الرسائل والرسوم

استخدم تحليل طول رسائل SMS على النص النهائي الكامل قبل الإرسال. تعتمد أسعار SMS على الوجهة وخدمة الحساب؛ وتُضاف رسوم مشغّل الاتصالات المنطبقة لكل جزء. يجمع مسار الإرسال أسعار المستلمين والرسوم المنطبقة، ثم يضرب الناتج في عدد أجزاء SMS المحسوب. ويعامل طلب MMS على أنه رسالة واحدة لأغراض هذا الحساب.

تمثل cost وpermsg سلاسل نصية منسّقة لمبالغ نقدية في الاستجابة القديمة. يبيّن carrier_fee_usd مكوّن رسوم مشغّل الاتصالات بعملة USD، وهو مشمول بالفعل في إجمالي الإرسال المحسوب؛ فلا تضفه مرة ثانية. يجب التحقق من الأسعار الفعلية وتوفر المسارات لحسابك. هذا الطلب ليس عملية للاستعلام عن السعر فقط.

تخصم الشيفرة التي تمت مراجعتها من الرصيد بعد نجاح مسار الإرسال عبر مشغّل الاتصالات، لكن قبول المشغّل والحفظ المحلي والفوترة ليست معاملة واحدة. قد يحدث خطأ أو تنتهي المهلة بعد قبول الطلب لدى مزوّد الخدمة الخارجي. لا يُتاح للعميل مفتاح لمنع تكرار تنفيذ الطلب: فقد يؤدي تكرار المرجع نفسه إلى الإرسال وفرض الرسوم مجددًا.

التسليم المحلي والنتائج المختلطة

يمكن قبول الأرقام المستضافة محليًا، بحالة accepted، ضمن تدفق الرسائل الواردة لدى MultiTEL دون إرسال عبر مشغّل اتصالات خارجي. بالنسبة إلى طلب تكون جميع وجهاته محلية، قد تتضمن الاستجابة accepted وmessage_id وprovider وdelivery_status. لا يضمن القبول المحلي نجاح وجهة إعادة التوجيه المُعدّة للمستلم.

افحص local_delivery_results وpartial عند وجودهما. قد تظهر للمستلم قيمة accepted تساوي true بينما تكون نتيجة إعادة توجيهه غير ناجحة. قد يتضمن الطلب المختلط مستلمين قُبل إرسال رسائلهم عبر مشغّل الاتصالات بحالة accepted، مع فشل الجزء المحلي. لا تُعِد محاولة إرسال الدفعة كاملة تلقائيًا: طابق نتائج كل مستلم وتحقق منها أولًا.

عندما تكون جميع الوجهات محلية ويُقبل الطلب، تُبلّغ الاستجابة في هذا المسار عن تكلفة إرسال صادرة تساوي صفرًا، بينما قد تظل رسوم الرسائل الواردة المعتادة مستحقة على المستلمين. لا تفسّر تكلفة الإرسال الصادرة الصفرية على أنها ضمان لعدم فرض رسوم على أي حساب.

إشعارات الاستدعاء الراجع وربط المعلومات

عند تقديم notifyurl، يتضمن إشعار الاستدعاء الراجع الأولي غلاف status وحقول استجابة تشمل message_id وreference وfrom وto وstatus وstatus_text وerror_code وtimestamp وaccepted. وقد توجد نتائج محلية أيضًا. خزّن معلومات الربط دون تسجيل بيانات اعتماد API أو محتويات الرسائل غير الضرورية.

لا يضيف هذا المعالج حقل توقيع إلى إشعار الاستدعاء الراجع الأولي ذلك. لا تستخدم إشعار استدعاء راجع لم يتم التحقق منه باعتباره تفويضًا مستقلًا لإجراء آخر. راجع إعداد التكامل أو إشعارات الويب المدعوم لحسابك، وطابق النتائج غير المؤكدة مع سجلات البوابة أو تحقق منها عبر الدعم. لا تفترض أن إشعارات الاستدعاء الراجع تصل مرة واحدة أو وفق ترتيب التسليم النهائي.

حالات الفشل والتعافي الآمن

قد تستخدم حالات فشل التحقق رمز API 403. وقد تضبط حالات الرفض المتعلقة بالموافقة على الحساب أو بسياسات P2P أو البلد حالة HTTP على 403 أيضًا، وتتضمن response.code قابلًا للقراءة آليًا. قد تستخدم حدود معدل الطلبات الرمز 429 مع معلومات إعادة المحاولة. وقد يُستخدم 503 أو 500 عند تعذر إتاحة سياسة أو عند فشل الإرسال أو الحفظ المحلي؛ كما قد تُعيد حالة عدم كفاية الرصيد في النظام القديم الرمز 500.

عند تلقي 429، التزم بـ Retry-After وأي قيمة في response.retry_after. وعند الرفض بسبب الحساب أو المرسل أو البلد أو المستلم، عالج السبب قبل إعادة المحاولة. وعند انتهاء المهلة أو غموض نتيجة الإرسال، احتفظ بوقت الطلب والمرجع والمعرّفات المُعادة، وافحص البوابة وتواصل مع الدعم قبل إعادة الإرسال. فغياب سجل للطلب وحده لا يثبت عدم قبول الطلب لدى أي مشغّل اتصالات.