تحمل حمولتا webhook أحداثَ المراسلة. فحدث حالة التسليم (DLR) يُبلّغ بنتيجة رسالة — message_id وتعداد حالة (accepted وdelivered وundelivered وexpired وrejected) وسبب خطأ وطوابع زمنية. وحدث الوارد (MO) يُبلّغ برسالة أرسلها مشترك إليك. وكلاهما نظيرا HTTP لإيصالات deliver_sm والرسائل الصادرة من المحمول في SMPP.
- تطبيقكيتم الإرسال عبر REST API أو SMPP
- منصة BroadNetتتحقق من كل رسالة وتوجّهها وتحتسب تكلفتها
- SMSC الخاص بالمشغّلاتصال مباشر مع المشغّل
- هاتف المشتركيتم تسليم الرسالة
عائلتا أحداث: الحالة والوارد
تُصدِر منصّة المراسلة نوعين مختلفين جوهريًا من الردود. فحدث حالة التسليم (DLR، إيصال التسليم) هو المتابعة غير المتزامنة لرسالة أرسلتها: يخبرك بما حدث لها في النهاية داخل شبكة المشغّل. وحدث الوارد (MO، الصادر من المحمول) غير مطلوب — رسالة أرسلها مشترك إلى أحد أرقامك أو ردّ على حملة. ويتشاركان نقل webhook وتوقيعه، لكن مخطّطيهما ومعنييهما يختلفان، لذا يتفرّع المستهلِك المحكم على مميّز نوع الحدث قبل تحليل الباقي. وكلاهما تعبيرٌ عند طبقة HTTP عمّا يُسلّمه SMPP كوحدات deliver_sm: رايةُ إيصال تميّز DLR عن MO على السلك، والتمييز نفسه حقلُ حدث صريح عبر HTTP.
حمولة حالة التسليم (DLR)
تُطابَق حمولةُ حالة التسليم مع الإرسال الأصلي عبر message_id الذي أسنده الخادم، وتُبلّغ بحالة مأخوذة من تعداد صغير، إضافةً إلى السبب والطوابع الزمنية التي تتيح قياس زمن الاستجابة وتسوية الفوترة. وتعداد الحالة هو صُلبها: يميّز حالة accepted/enroute الوسيطة عن الحالات النهائية، ويفصل حالة delivered الإيجابية عن الطرق العدّة التي قد تفشل بها رسالة. وتحمل الحالات النهائية السلبية رمز خطأ وسببًا مقروءًا للبشر بحيث يستطيع المستهلِك تقرير ما إذا كانت الوجهة سيئة بشكل دائم (فيكبتها) أو كان الفشل عابرًا (فيُعيد الإرسال بأمان). وتشمل الطوابع الزمنية عادةً وقت قبول المنصّة للرسالة ووقت وقوع الحالة النهائية.
{
"event": "message.delivered",
"message_id": "01HZY8Q3M6",
"to": "+15551234567",
"status": "delivered",
"error": null,
"reason": null,
"submitted_at": "2026-07-19T09:15:22Z",
"done_at": "2026-07-19T09:15:25Z",
"sequence": 3
}تعداد حالة التسليم
توحيدُ قيم الحالة هو ما يتيح لمستهلِك واحد التعاملَ مع كل مشغّل، لأن استجابات الشبكة الخام تتباين بشدّة. فالتعداد القانوني يطابقها بحفنة حالات ذات دلالات واضحة: هل الحالة نهائية، وهل هي نجاح. وقد تُستبدَل الحالات الوسيطة (accepted وenroute) بحدث لاحق للمعرّف نفسه، وهذا بالضبط سبب حمل الحمولات تسلسلًا أو طابعًا زمنيًا وسبب تطبيق المستهلِكين قاعدةَ الترتيب الذاتي من موثوقية webhook — فحالة accepted متأخّرة يجب ألّا تطمس delivered سابقة.
| status | الطرفية | المعنى |
|---|---|---|
| accepted | No | قبلت المنصة الرسالة للتسليم |
| enroute | No | سُلّمت إلى المشغّل، في انتظار الإيصال |
| delivered | نعم | تم تأكيد التسليم إلى الهاتف المحمول |
| undelivered | نعم | لم يتمكن المشغّل من التسليم (انظر الخطأ/السبب) |
| expired | نعم | انقضت فترة الصلاحية قبل التسليم |
| rejected | نعم | مرفوضة (رقم غير صالح، مرسِل محظور، مرشّح الرسائل المزعجة) |
| unknown | نعم | لم يُرجع المشغّل حالة نهائية محددة |
حمولة الرسالة الواردة (MO)
يحمل الحدث الوارد محتوى الرسالة إضافةً إلى التوجيه اللازم للردّ ولمطابقة محادثة. والحقول الحرجة هي from (رقم MSISDN للمشترك بصيغة E.164) وto (الرقم أو الرمز القصير/الطويل الذي راسلوه) والنص text؛ وإلى جانبها معرّف رسالة للرسالة الواردة نفسها، وطابع زمني لوقت الاستلام، و — لأن الرسائل الواردة تخضع لقواعد الترميز والتجزئة نفسها كالصادرة — الترميز encoding، وللرسالة متعدّدة الأجزاء مرجعُ التسلسل ومؤشّرات الأجزاء بحيث يستطيع المستهلِك إعادة تجميع النص الكامل. والأحداث الواردة هي ما يقود حملات الكلمات المفتاحية والمحادثات ثنائية الاتجاه وتدفّقات الامتثال STOP/HELP.
{
"event": "message.inbound",
"message_id": "01HZY8R7T0",
"from": "+15551234567",
"to": "44160",
"text": "STOP",
"encoding": "GSM7",
"received_at": "2026-07-19T09:20:11Z",
"concat": { "ref": null, "part": 1, "total": 1 }
}تصنيف أنواع الأحداث
إلى جانب DLR وMO، تُصدِر المنصّة أحداث دورة حياة وحساب، ومخطّط تسمية متّسق — سلسلة resource.action منقّطة — يتيح للمستهلِك الاشتراك فيها وتوجيهها بنظافة. فأحداث حالة التسليم صيغٌ من message.<status>؛ والحدث الوارد هو message.inbound. والتجميع حسب بادئة المورد يعني أن المستهلِك يستطيع مطابقة message.* لكل ما يخصّ رسالة وحجز بادئات أخرى لأحداث الحساب أو الأرقام. وينبغي أن يحمل كل حدث أيضًا معرّف حدث ثابت (يُستخدم قيمةَ nonce للتوقيع ومفتاحَ إزالة التكرار) وسلسلة النوع، بحيث يكون المميّز ومفتاح التكافؤ حاضرين دائمًا.
| نوع الحدث | العائلة | يُطلق عندما |
|---|---|---|
| message.accepted | الحالة (DLR) | تم قبول الرسالة للتسليم |
| message.delivered | الحالة (DLR) | تم تأكيد التسليم إلى الهاتف المحمول |
| message.undelivered | الحالة (DLR) | فشل المشغّل في التسليم |
| message.expired | الحالة (DLR) | انقضت فترة الصلاحية |
| message.rejected | الحالة (DLR) | رُفضت الرسالة في مرحلة سابقة (upstream) |
| message.inbound | الوارد (MO) | أرسل لك أحد المشتركين رسالة |
مطابقة DLR بـ HTTP مع deliver_sm في SMPP
ردّ حالة التسليم بـ HTTP وإيصال التسليم بـ SMPP هما المعلومة نفسها بترميزين، والمنصّة التي تجسر بين REST وSMPP تترجم بينهما. ففي SMPP يصل الإيصال كوحدة deliver_sm يُعلِّم esm_class عليها أنها إيصال؛ ويحمل حقل الرسالة القصيرة فيها إيصالًا نصيًا بحقول id وstat وerr، وتحمل TLV للـ message_state الحالةَ الرقمية. وترفع DLR بـ HTTP تلك إلى JSON: يُطابَق رمز stat في SMPP مع تعداد الحالة القانوني، وتُطابَق قيمة err مع حقل error، ويُطابَق وقتا submit/done في الإيصال مع submitted_at/done_at. وفهم هذه المطابقة هو ما يتيح لمسار شفرة واحد لمعالجة التسليم أن يخدم كلتا الوسيلتين؛ وصيغة إيصال SMPP ووحدة deliver_sm موثّقتان بالتفصيل في مرجع SMPP.
| حقل إيصال SMPP | حقل HTTP DLR | ملاحظة |
|---|---|---|
| id (الإيصال) | message_id | يرتبط بـ submit_sm / POST الأصلي |
| stat (DELIVRD/UNDELIV/EXPIRED/REJECTD) | status | الرمز النصي يقابل قيمة التعداد القياسية |
| err | error | رمز خطأ المشغّل/الشبكة |
| message_state TLV | status (قيمة رقمية مقابلة) | الحالة الرقمية في SMPP خلف الرمز النصي |
| تاريخ التقديم / تاريخ الإنجاز | submitted_at / done_at | طوابع زمنية لزمن الاستجابة والتسوية |
الأسئلة المتكررة
ماذا يوجد في حمولة webhook لحالة التسليم (DLR)؟
المعرّف message_id الذي أسنده الخادم ويُطابِقها مع إرسالك، وحالة مأخوذة من تعداد قانوني (accepted وenroute وdelivered وundelivered وexpired وrejected وunknown)، ورمز خطأ وسبب مقروء للبشر عند الفشل، وطوابع زمنية لوقت تقديم الرسالة ووقت وقوع الحالة النهائية.
كيف يختلف الحدث الوارد (MO) عن DLR؟
الـ DLR هو النتيجة غير المتزامنة لرسالة أرسلتها. والحدث الوارد (MO) غير مطلوب — رسالة أرسلها مشترك إلى رقمك أو ردّ على حملة — يحمل from وto والنص والترميز، وللرسائل متعدّدة الأجزاء حقولَ التسلسل. ويتشاركان النقل والتوقيع لكن مخطّطيهما مختلفان، لذا يتفرّع المستهلِكون على نوع الحدث أولًا.
لماذا يُوحَّد تعداد حالة التسليم؟
لأن استجابات المشغّلين الخام تتباين تباينًا هائلًا. ومطابقتها بتعداد قانوني صغير بدلالات نهائية-ونجاح واضحة تتيح لمستهلِك واحد التعامل مع كل مشغّل بانتظام، وتتيح لك أن تقرّر من الحالة وحدها ما إذا كنت ستكبت وجهة سيئة، أو تعيد إرسال فشل عابر، أو تسجّل تسليمًا مؤكَّدًا.
كيف أوقف حالة accepted متأخّرة من طمس delivered سابقة؟
استخدم حقول الترتيب الذاتي. تحمل حمولات DLR طابعًا زمنيًا وغالبًا رقم تسلسل؛ ويقارنهما المستهلِك بآخر حالة سجّلها لذلك المعرّف ويتجاهل أي حدث أقدم مما لديه، بحيث لا تطمس حالةٌ وسيطة غير مرتّبة حالةً نهائية أبدًا.
كيف تُطابَق DLR بـ HTTP مع إيصال deliver_sm في SMPP؟
يحملان المعلومة نفسها. ففي SMPP الإيصال وحدة deliver_sm مُعلَّمة في esm_class، بحقول id وstat وerr وTLV للـ message_state. وتطابق DLR بـ HTTP رمزَ stat مع تعداد الحالة، وerr مع error، وطوابع الإيصال الزمنية مع submitted_at/done_at — بحيث يخدم مسارُ معالجة تسليم واحد كلتا الوسيلتين.
ما الحقول التي تتيح لي إعادة تجميع رسالة SMS واردة متعدّدة الأجزاء؟
حقول التسلسل: مرجع يربط الأجزاء، ومؤشّر الجزء، والعدد الإجمالي. ولأن الرسائل الواردة تخضع لقواعد الترميز والتجزئة نفسها كالصادرة، تصل رسالةٌ واردة طويلة كعدّة أحداث MO يخيطها المستهلِك معًا بالترتيب باستخدام تلك الحقول.
مواصفات المصدر
تستند هذه الصفحة إلى المعايير المنشورة. يفتح في علامة تبويب جديدة.