الرسائل
الرسالة هي SMS واحدة إلى رقم واحد أو منه. تمر الرسائل الصادرة بالحالات queued وrouted وsending وsent وتنتهي بإحدى delivered أو failed أو blocked، أما الواردة فحالتها received. انظر تتبّع التسليم.
كائن الرسالة
Section titled “كائن الرسالة”| الحقل | النوع | الوصف |
|---|---|---|
id |
string | msg_… |
direction |
string | outbound أو inbound. |
to |
string | المستلم بصيغة E.164. في الواردة: رقم شريحتك، أو "" إذا كان مجهولا. |
from |
string أو null | في الواردة: المرسل. وnull في الصادرة. |
body |
string | النص. رسائل التحقق تظهر [verification code hidden]. |
status |
string | queued أو routed أو sending أو sent أو delivered أو failed أو blocked أو received. |
segments |
integer | عدد أجزاء SMS التي قُسّم إليها النص. |
encoding |
string | GSM7 أو UCS2. |
deviceId |
string أو null | الهاتف الذي أرسلها أو استقبلها. |
simId |
string أو null | الشريحة المستخدمة. |
provider |
string أو null | device، أو sandbox لمفاتيح sf_test_. وnull حتى التوجيه. |
errorCode |
string أو null | سبب failed أو blocked. انظر رموز الفشل. |
createdAt |
string | وقت قبولها. |
sentAt |
string أو null | وقت قبول شركة الاتصالات لها. |
deliveredAt |
string أو null | وقت تأكيد جهاز المستلم. |
metadata |
object أو null | بيانات JSON الخاصة بك من طلب الإرسال. رسائل الحملات تحمل campaignId، ورسائل التحقق تحمل verificationId. |
إرسال رسالة
Section titled “إرسال رسالة”/v1/messagesmessages:sendيضع رسالة في الطابور لكل مستلم. يعيد 201 مع رسالة لكل مستلم بترتيب الطلب. يدعم Idempotency-Key. المستلمون في القائمة السوداء تعود رسائلهم بالحالة status: "blocked" وerrorCode: "blacklisted"، والباقي queued.
| حقل المحتوى | النوع | إلزامي | الوصف | القيود |
|---|---|---|---|---|
to |
string أو string[] | نعم | أرقام المستلمين. | E.164، من 1 إلى 100 رقم. |
body |
string | نعم | النص. | من 1 إلى 1600 حرف. |
deviceId |
string | لا | أرسل من هذا الهاتف. | يجب أن يتبع مؤسستك. |
simId |
string | لا | أرسل من هذه الشريحة. | يجب أن تتبع مؤسستك. |
poolId |
string | لا | بالتناوب على هواتف المجموعة المتصلة، مع التحويل عند التعطل. | يجب أن تتبع مؤسستك. |
scheduledAt |
string | لا | أرسل في هذا الوقت. | ISO 8601، بحد أقصى سنة. |
metadata |
object | لا | تعود مع الرسالة وفي webhooks. | كائن JSON حتى 4 KB. |
curl https://api.smsfabric.com/v1/messages \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1042-shipped" \ -d '{"to": ["+201001234567", "+201001234568"], "body": "Your order #1042 has shipped.", "metadata": {"orderId": "1042"}}'{ "data": [ { "id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4", "direction": "outbound", "to": "+201001234567", "from": null, "body": "Your order #1042 has shipped.", "status": "queued", "segments": 1, "encoding": "GSM7", "deviceId": null, "simId": null, "provider": null, "errorCode": null, "createdAt": "2026-11-19T10:15:02.114Z", "sentAt": null, "deliveredAt": null, "metadata": { "orderId": "1042" } }, { "id": "msg_j4l6n8p1r3t5v7x9z2b4d6f8", "direction": "outbound", "to": "+201001234568", "from": null, "body": "Your order #1042 has shipped.", "status": "blocked", "segments": 1, "encoding": "GSM7", "deviceId": null, "simId": null, "provider": null, "errorCode": "blacklisted", "createdAt": "2026-11-19T10:15:02.118Z", "sentAt": null, "deliveredAt": null, "metadata": { "orderId": "1042" } } ]}| الخطأ | متى |
|---|---|
400 validation_failed |
رقم غير صالح (errors[].field بالقيمة to[<index>])، أو أكثر من 100 مستلم، أو نص فارغ أو طويل جدا، أو metadata أكبر من 4 KB، أو scheduledAt بعد أكثر من سنة. لا يُرسل شيء. |
404 not_found |
deviceId أو simId أو poolId لا يتبع مؤسستك. |
409 idempotency_in_progress و422 idempotency_key_reused |
انظر منع التكرار. |
عرض الرسائل
Section titled “عرض الرسائل”/v1/messagesmessages:readيعيد الرسائل من الأحدث إلى الأقدم، مقسمة إلى صفحات.
| الاستعلام | النوع | الوصف |
|---|---|---|
direction |
string | outbound أو inbound. |
status |
string | حالة رسالة واحدة. |
deviceId |
string | الرسائل الموجهة إلى هذا الهاتف أو الواردة إليه. |
campaignId |
string | الرسائل التي أرسلتها هذه الحملة. |
q |
string | رقم هاتف أو جزء منه (من 3 إلى 15 رقما مع + اختيارية)، يُطابق في to وfrom. |
from |
string | أُنشئت في هذا الوقت أو بعده (ISO 8601). |
to |
string | أُنشئت في هذا الوقت أو قبله (ISO 8601). |
limit |
integer | من 1 إلى 200، والافتراضي 50. |
cursor |
string | nextCursor من الصفحة السابقة. |
curl "https://api.smsfabric.com/v1/messages?status=failed&limit=2" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "msg_k5m7o9q2s4u6w8y1a3c5e7g9", "direction": "outbound", "to": "+966501234567", "from": null, "body": "Your appointment is confirmed for 20 November at 09:30.", "status": "failed", "segments": 1, "encoding": "GSM7", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "provider": "device", "errorCode": "no_service", "createdAt": "2026-11-19T09:58:40.002Z", "sentAt": null, "deliveredAt": null, "metadata": null } ], "nextCursor": null}قراءة رسالة
Section titled “قراءة رسالة”/v1/messages/:idmessages:readيعيد الرسالة مع events[]، سجلها الزمني من الأقدم إلى الأحدث. لكل حدث id (evt_…) وtype وstatus (أو null لخطوات التوجيه) وdeviceId وdetail وcreatedAt.
| المسار | النوع | الوصف |
|---|---|---|
id |
string | معرّف الرسالة. |
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.", "status": "sent", "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": null, "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_a5c7e9g2i4k6m8o1q3s5u7w9", "type": "sent", "status": "sent", "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "detail": { "source": "device" }, "createdAt": "2026-11-19T10:15:05.870Z" } ]}| الخطأ | متى |
|---|---|
404 not_found |
لا توجد رسالة بهذا المعرّف في مؤسستك. |
إحصاءات الرسائل
Section titled “إحصاءات الرسائل”/v1/messages/statsmessages:readأعداد يومية لآخر days يوما بتوقيت UTC تنتهي اليوم، ومجاميع للفترة نفسها. يحسب sent للصادرة الرسائل التي حالتها sending أو sent أو delivered.
| الاستعلام | النوع | الوصف |
|---|---|---|
days |
integer | من 1 إلى 31، والافتراضي 7. |
curl "https://api.smsfabric.com/v1/messages/stats?days=3" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "days": [ { "date": "2026-11-17", "sent": 412, "delivered": 398, "failed": 6 }, { "date": "2026-11-18", "sent": 530, "delivered": 511, "failed": 9 }, { "date": "2026-11-19", "sent": 188, "delivered": 170, "failed": 2 } ], "totals": { "sent": 1130, "delivered": 1079, "failed": 17, "queued": 14, "received": 63 }}تصدير الرسائل بصيغة CSV
Section titled “تصدير الرسائل بصيغة CSV”/v1/messages/export.csvlogs:exportيبث كل رسالة تطابق عوامل التصفية بصيغة text/csv. يقبل عوامل تصفية عرض الرسائل نفسها، دون limit وcursor. الخلايا التي تبدأ بـ = أو + أو - أو @ تُسبق بعلامة ' كي لا تنفذها جداول البيانات كمعادلات، وهذا يشمل أرقام الهواتف.
curl "https://api.smsfabric.com/v1/messages/export.csv?from=2026-11-01T00:00:00Z&to=2026-11-30T23:59:59Z" \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -o messages-november.csvid,direction,to,from,body,status,segments,encoding,deviceId,simId,provider,errorCode,createdAt,sentAt,deliveredAtmsg_q8v2k4n6p1r3t5w7y9z0b2c4,outbound,'+201001234567,,Your order #1042 has shipped.,delivered,1,GSM7,dev_m4p7s2v5y8b1e4h7k0n3q6t9,sim_r2t4v6x8z1b3d5f7h9j2l4n6,device,,2026-11-19T10:15:02.114Z,2026-11-19T10:15:05.870Z,2026-11-19T10:15:09.402Z