تتبّع التسليم
يعود الإرسال بمجرد دخول الرسالة الطابور. كل ما بعد ذلك، من استلام الهاتف لها حتى تقرير التسليم من جهاز المستلم، يجري بشكل غير متزامن. يمكنك متابعتها بطريقتين: أن تسأل عن الرسالة، أو أن تدع SMSFabric تتصل بك عبر webhook.
حالات الرسالة
Section titled “حالات الرسالة”queuedroutedsendingsentdeliveredfailedblocked
| الحالة | المعنى |
|---|---|
queued |
مقبولة وتنتظر: هاتفا، أو موعد scheduledAt، أو نافذة الإرسال. |
routed |
أُسندت إلى هاتف (وشريحة) وطُلب منه إرسالها. |
sending |
سلّمها الهاتف إلى الشبكة اللاسلكية. |
sent |
قبلتها شركة الاتصالات. |
delivered |
أكد جهاز المستلم التسليم. حالة نهائية. |
failed |
تعذر إرسالها، وerrorCode يبين السبب. حالة نهائية. |
blocked |
لم تُرسل بسبب القائمة السوداء أو إلغاء الاشتراك أو إلغاء حملة، وerrorCode يبين أيها. حالة نهائية. |
received |
رسالة واردة من شخص آخر. حالة نهائية. انظر استقبال الرسائل. |
الحالات تتقدم ولا تتراجع. أي تقرير متأخر من هاتف قد يعيد الرسالة إلى الوراء يُتجاهل.
الاستعلام عن رسالة
Section titled “الاستعلام عن رسالة”يعيد GET /v1/messages/:id الرسالة مع events[]، سجلها الزمني الكامل من الأقدم إلى الأحدث. يحتاج المفتاح إلى messages:read.
curl https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const message = await sf.messages.get('msg_q8v2k4n6p1r3t5w7y9z0b2c4');console.log(message.status, message.errorCode);for (const event of message.events) { console.log(event.createdAt, event.type, event.deviceId ?? '');}import osimport requests
res = requests.get( "https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}, timeout=30,)res.raise_for_status()message = res.json()print(message["status"], message["errorCode"])for event in message["events"]: print(event["createdAt"], event["type"], event["deviceId"] or "")<?php$ch = curl_init('https://api.smsfabric.com/v1/messages/msg_q8v2k4n6p1r3t5w7y9z0b2c4');curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$message = json_decode(curl_exec($ch), true);echo $message['status'] . "\n";foreach ($message['events'] as $event) { echo $event['createdAt'] . ' ' . $event['type'] . "\n";}{ "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. الاستعلامات تُحتسب ضمن حدود المعدل.
الإشعار عبر webhooks
Section titled “الإشعار عبر 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.
البحث عن الرسائل
Section titled “البحث عن الرسائل”يعرض 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 |
تتحدث القائمة مباشرة. انظر الرسائل في البوابة لشرح خطوة بخطوة.
رموز الفشل
Section titled “رموز الفشل”قيمة 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 |
أُوقفت المؤسسة. |
انظر حل المشكلات للحلول.