تخطَّ إلى المحتوى

تتبّع التسليم

يعود الإرسال بمجرد دخول الرسالة الطابور. كل ما بعد ذلك، من استلام الهاتف لها حتى تقرير التسليم من جهاز المستلم، يجري بشكل غير متزامن. يمكنك متابعتها بطريقتين: أن تسأل عن الرسالة، أو أن تدع SMSFabric تتصل بك عبر webhook.

  1. queued
  2. routed
  3. sending
  4. sent
  5. deliveredfailedblocked
تنتهي كل رسالة صادرة بإحدى الحالات النهائية: delivered أو failed أو blocked.
الحالة المعنى
queued مقبولة وتنتظر: هاتفا، أو موعد scheduledAt، أو نافذة الإرسال.
routed أُسندت إلى هاتف (وشريحة) وطُلب منه إرسالها.
sending سلّمها الهاتف إلى الشبكة اللاسلكية.
sent قبلتها شركة الاتصالات.
delivered أكد جهاز المستلم التسليم. حالة نهائية.
failed تعذر إرسالها، وerrorCode يبين السبب. حالة نهائية.
blocked لم تُرسل بسبب القائمة السوداء أو إلغاء الاشتراك أو إلغاء حملة، وerrorCode يبين أيها. حالة نهائية.
received رسالة واردة من شخص آخر. حالة نهائية. انظر استقبال الرسائل.

الحالات تتقدم ولا تتراجع. أي تقرير متأخر من هاتف قد يعيد الرسالة إلى الوراء يُتجاهل.

يعيد GET /v1/messages/:id الرسالة مع events[]، سجلها الزمني الكامل من الأقدم إلى الأحدث. يحتاج المفتاح إلى messages:read.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"direction": "outbound",
"to": "+201001234567",
"from": null,
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"status": "delivered",
"segments": 1,
"encoding": "GSM7",
"deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9",
"simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6",
"provider": "device",
"errorCode": null,
"createdAt": "2026-11-19T10:15:02.114Z",
"sentAt": "2026-11-19T10:15:05.870Z",
"deliveredAt": "2026-11-19T10:15:09.402Z",
"metadata": { "orderId": "1042" },
"events": [
{ "id": "evt_w1y3a5c7e9g2i4k6m8o1q3s5", "type": "queued", "status": "queued", "deviceId": null, "detail": null, "createdAt": "2026-11-19T10:15:02.120Z" },
{ "id": "evt_x2z4b6d8f1h3j5l7n9p2r4t6", "type": "routed", "status": "routed", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6" }, "createdAt": "2026-11-19T10:15:02.141Z" },
{ "id": "evt_y3a5c7e9g2i4k6m8o1q3s5u7", "type": "dispatched", "status": null, "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "channel": "ws" }, "createdAt": "2026-11-19T10:15:02.380Z" },
{ "id": "evt_z4b6d8f1h3j5l7n9p2r4t6v8", "type": "sending", "status": "sending", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.210Z" },
{ "id": "evt_a5c7e9g2i4k6m8o1q3s5u7w9", "type": "sent", "status": "sent", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.870Z" },
{ "id": "evt_b6d8f1h3j5l7n9p2r4t6v8x1", "type": "delivered", "status": "delivered", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:09.402Z" }
]
}

إلى جانب تغيرات الحالة، يسجل السجل الزمني خطوات التوجيه. لهذه الأحداث status: null أو status: "routed":

type الحدث المعنى
routed أُسندت إلى هاتف، وdetail.simId هي الشريحة.
wake_sent كان الهاتف غير متصل فأُوقظ بإشعار.
dispatched استلم الهاتف الرسالة (detail.channel هي ws أو pull).
ack_timeout وdevice_rejected لم يقبل الهاتف الرسالة في الوقت المحدد، أو رفضها.
rerouted نُقلت إلى هاتف آخر في المجموعة (detail.from وdetail.reason).
retry أُعيد إرسالها بعد أن أبلغ الهاتف عن فشل (detail.reason).

استعلم باعتدال: كل بضع ثوان لرسالة ينتظرها مستخدم، وتوقف عند الحالة النهائية. للأحجام الكبيرة استخدم webhooks. الاستعلامات تُحتسب ضمن حدود المعدل.

اشترك بنقطة نهاية webhook في هذه الأحداث لترسل إليك SMSFabric الرسالة عند كل تغيير:

الحدث يُرسل عندما تصبح الرسالة
message.queued queued
message.sent sent
message.delivered delivered
message.failed failed
message.received received (واردة)

حقل data في الحدث هو الرسالة بالشكل نفسه الذي يعيده GET /v1/messages/:id دون events، ومعه metadata الخاصة بك. استخدم metadata لتعرف الطلب أو المستخدم أو التذكرة التي تخص الرسالة.

{
"id": "evt_c7e9g2i4k6m8o1q3s5u7w9y2",
"type": "message.delivered",
"createdAt": "2026-11-19T10:15:09.455Z",
"orgId": "org_n5q8t1w4z7c0f3i6l9o2r5u8",
"data": {
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"status": "delivered",
"to": "+201001234567",
"deliveredAt": "2026-11-19T10:15:09.402Z",
"metadata": { "orderId": "1042" }
}
}

(اختُصر data هنا.) لا يوجد webhook للحالات routed وsending وblocked. الرسالة المحظورة تكون نهائية أصلا في استجابة 201 لطلب الإرسال.

اضبط نقاط النهاية وتحقق من تواقيعها في Webhooks.

يعرض GET /v1/messages الرسائل من الأحدث إلى الأقدم، مع عوامل تصفية:

الاستعلام مثال يطابق
status failed حالة واحدة.
direction inbound outbound أو inbound.
deviceId dev_m4p7… الرسائل الموجهة إلى هذا الهاتف.
campaignId cmp_… رسائل حملة واحدة.
q 4567 رقم هاتف أو جزء منه في to أو from.
from وto 2026-11-01T00:00:00Z أُنشئت ضمن هذا النطاق الزمني.

النتائج مقسمة إلى صفحات عبر limit وcursor (انظر تقسيم الصفحات). يعيد GET /v1/messages/stats?days=7 أعداد المرسلة والمسلّمة والفاشلة لكل يوم، ويبث GET /v1/messages/export.csv عوامل التصفية نفسها بصيغة CSV مع الصلاحية logs:export.

البيانات نفسها في البوابة

Section titled “البيانات نفسها في البوابة”

تقرأ شاشة الرسائل في البوابة من الواجهة نفسها، فما تراه هناك هو ما تحصل عليه شيفرتك:

في الواجهة البرمجية في البوابة
GET /v1/messages مع عوامل التصفية قائمة الرسائل مع الحالة والاتجاه والجهاز ومن تاريخ وإلى تاريخ وابحث بالرقم
status عمود الحالة
deviceId وsimId عمود المسار (لم يُوجَّه بعد ما دامت queued)
segments عمود الأجزاء
events[] المسار الزمني في لوحة الرسالة
errorCode الخطأ في لوحة الرسالة
GET /v1/messages/export.csv تصدير CSV

تتحدث القائمة مباشرة. انظر الرسائل في البوابة لشرح خطوة بخطوة.

قيمة errorCode في رسالة failed أو blocked:

errorCode الحالة المعنى
blacklisted blocked الرقم في قائمتك السوداء.
opted_out blocked رد المستلم بكلمة STOP (رسائل الحملات).
campaign_canceled blocked أُلغيت الحملة قبل أن يستلم أي هاتف الرسالة.
no_device_available failed لم يستطع أي هاتف مفعّل استلام الرسالة.
device_unavailable failed عُطّل الهاتف المسند أو فُصل.
device_unpaired failed أُلغي اقتران الهاتف قبل أن يأخذ الرسالة، ولم يستطع هاتف آخر متصل في مجموعته أخذها. أعد إرسالها.
device_rejected failed رفض الهاتف الرسالة.
radio_off، no_service، generic_failure، limit_exceeded، null_pdu، short_code_not_allowed، short_code_never_allowed failed يبلّغ عنها Android عندما تعجز الشريحة عن الإرسال. تحقق من الإشارة ووضع الطيران ورصيد الشريحة.
sim_not_found failed الشريحة المختارة لم تعد في الهاتف.
tenant_suspended failed أُوقفت المؤسسة.

انظر حل المشكلات للحلول.