الحالات الست للرسالة
لكل رسالة حالة تقرؤها عبر GET /v1/messages/{id} وتصلك إلى الـ webhook.
- queued — قبلتها EnvoiSMS.ma وهي في انتظار الإرسال.
- sent — سُلّمت إلى الشبكة ولم يُصدر المشغّل حكمه بعد.
- delivered — يؤكد المشغّل وصولها إلى الهاتف.
- failed — رفضها المشغّل أو المسار، ويذكر error_code السبب.
- undeliverable — لا يمكن الوصول إلى الرقم (غير موجود أو ملغى).
- unconfirmed — قبلت الشبكة الرسالة لكنها لم تُصدر نتيجة خلال نافذة الإبلاغ؛ وإشعار DLR متأخر يحلّ محل هذه الحالة.
من أين يأتي إشعار التسليم
يُصدر مشغّل المستلم إشعار DLR وليس نحن، ونحن ننقله كما هو. الهاتف المغلق أو خارج التغطية يؤخّر التسليم ومعه الإشعار، أحيانًا لساعات. لذلك فحالة sent ليست فشلًا بل انتظار.
قراءة الفشل: error_code
تحمل الرسالة الفاشلة أو غير القابلة للتسليم رمزًا قصيرًا وثابتًا في error_code يمكن لبرنامجك أن يتصرف بحسبه.
- DLR_<حالة الشبكة> — جاء الفشل من تقرير المشغّل (مثل DLR_REJECTD وDLR_EXPIRED وDLR_UNDELIV).
- GATEWAY_* — فشل في توجيه EnvoiSMS.ma قبل الوصول إلى الشبكة.
- META_* — رفض من واتساب للرسائل المرسلة عبر هذه القناة.
- يُعامَل أي رمز غير معروف كفشل نهائي، فقد تظهر قيم جديدة.
استقبال الحالات عبر webhook
سجّل رابطًا واشترك في أحداث message.sent وmessage.delivered وmessage.failed. كل استدعاء موقَّع: تحقّق من الترويسة X-EnvoiSMS-Signature-256 (HMAC-SHA256 للطابع الزمني والمحتوى) وارفض أي طابع زمني يتجاوز 5 دقائق. تعود البيانات الوصفية التي أرسلتها مع الرسالة داخل الـ webhook لتربط الحالة بطلبك أو مستخدمك.
ما الذي يُحتسب عليك
تُستردّ قيمة الرسالة الفاشلة فور توفّر الدليل على أن الشبكة لم تحتسبها، وحين يغيب هذا الدليل يراجعها فريقنا بدل الاسترداد دون تحقق. ولرمز OTP تولّده بنفسك، أضف metadata.purpose = "otp": عند فشل نهائي نحو رقم مغربي، يُعاد إرسال الرمز الذي ما زال صالحًا (أقل من 10 دقائق) مرة واحدة عبر مسار SMS آخر دون تكلفة إضافية.