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

الرسائل

الرسالة هي SMS واحدة إلى رقم واحد أو منه. تمر الرسائل الصادرة بالحالات queued وrouted وsending وsent وتنتهي بإحدى delivered أو failed أو blocked، أما الواردة فحالتها received. انظر تتبّع التسليم.

الحقل النوع الوصف
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.
POST/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 انظر منع التكرار.
GET/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
}
GET/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 لا توجد رسالة بهذا المعرّف في مؤسستك.
GET/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 }
}
GET/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.csv
id,direction,to,from,body,status,segments,encoding,deviceId,simId,provider,errorCode,createdAt,sentAt,deliveredAt
msg_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