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

إرسال الرسائل

تضع POST /v1/messages نصا في الطابور لمستلم واحد أو حتى 100 مستلم. ترد الواجهة فورا بالحالة 201 Created ورسالة لكل مستلم. بعدها يستلم أحد الهواتف الرسالة ويرسلها، وتتابعها أنت عبر التتبع وwebhooks.

يحتاج المفتاح إلى الصلاحية messages:send. أرسل دائما الترويسة Idempotency-Key حتى لا تُرسل الرسالة مرتين إذا أعدت المحاولة بعد انتهاء المهلة (انظر منع التكرار).

نافذة طرفيّة
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",
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"metadata": { "orderId": "1042" }
}'

الاستجابة:

{
"data": [
{
"id": "msg_q8v2k4n6p1r3t5w7y9z0b2c4",
"direction": "outbound",
"to": "+201001234567",
"from": null,
"body": "Your order #1042 has shipped. Track it at acme.example/t/1042",
"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" }
}
]
}

تمتلئ الحقول deviceId وsimId وprovider بعد توجيه الرسالة إلى هاتف.

الحقل النوع إلزامي الوصف
to string أو string[] نعم رقم واحد، أو مصفوفة من 1 إلى 100 رقم بصيغة E.164 (+201001234567). يُتحقق من كل رقم بمكتبة libphonenumber.
body string نعم من 1 إلى 1600 حرف، ويُقسّم تلقائيا إلى أجزاء SMS.
deviceId string لا أرسل من هذا الهاتف (dev_…).
simId string لا أرسل من هذه الشريحة (sim_…)، ويُستخدم هاتفها تبعا لذلك.
poolId string لا أرسل عبر هذه المجموعة بالتناوب على هواتفها المتصلة، مع التحويل عند التعطل.
scheduledAt تاريخ ISO 8601 لا احتفظ بالرسالة حتى هذا الوقت، بحد أقصى سنة واحدة.
metadata object لا بيانات JSON خاصة بك حتى 4 KB، تعود مع الرسالة وفي كل webhook يخصها.

إذا كان deviceId أو simId أو poolId غير معروف يعود 404 not_found، وكذلك إذا كان يتبع مؤسسة أخرى. الرقم غير الصالح يعيد 400 validation_failed مع errors[].field بالقيمة to[<index>]، ولا يُرسل شيء.

مرّر مصفوفة. تحصل على رسالة لكل مستلم بالترتيب نفسه، لكل منها id وحالة خاصة بها.

{
"to": ["+201001234567", "+201001234568", "+966501234567"],
"body": "The Nasr City branch opens at 10:00 tomorrow."
}

الرقم الموجود في القائمة السوداء لا يُفشل الطلب. تعود رسالته بالحالة status: "blocked" وerrorCode: "blacklisted" ولا تغادر الخادم، وتدخل الرسائل الأخرى الطابور.

لأكثر من 100 مستلم أو لنص مخصص لكل شخص، استخدم حملة.

إذا لم ترسل حقول توجيه، تختار SMSFabric الهاتف بهذا الترتيب:

  1. simId أو deviceId إن أرسلت أحدهما.
  2. poolId: بالتناوب على هواتف المجموعة المتصلة.
  3. الشريحة الافتراضية للمؤسسة (تُضبط من الأجهزة أو عبر POST /v1/devices/:id/sims/:simId/default).
  4. بالتناوب على كل الهواتف المتصلة.

إذا لم يكن أي هاتف متصلا، يُوقظ آخر هاتف ظهر عبر إشعار وتنتظره الرسالة. وإذا لم يستطع أي هاتف استلامها إطلاقا تفشل مع errorCode: "no_device_available".

الإرسال مع poolId يضيف التحويل عند التعطل: إذا لم يقبل الهاتف الرسالة خلال 10 ثوان، أو رفضها، أو انقطع اتصاله، تنتقل الرسالة إلى هاتف متصل آخر في المجموعة. وعندما يبلّغ الهاتف عن فشل الإرسال، تُعاد المحاولة حتى maxRetries مرة (2 افتراضيا، في التفضيلات)، على هاتف آخر في المجموعة إن وجد، وإلا على الهاتف نفسه.

يلتزم كل هاتف بفترة انتظار بين الرسائل (3 ثوان افتراضيا مع تفاوت عشوائي حتى ثانيتين) لحماية شرائحك. خطط للسرعة على هذا الأساس: يرسل الهاتف الواحد نحو 14 رسالة في الدقيقة بالإعدادات الافتراضية. أضف هواتف إلى مجموعة لتسرع.

تبيّن الواجهة كيف ستحتسب شركة الاتصالات النص:

الترميز يُستخدم عندما جزء واحد كل جزء من نص أطول
GSM7 كل الأحرف من أبجدية GSM 03.38 160 حرفا 153 حرفا
UCS2 أي حرف آخر، ومنه العربية والرموز التعبيرية 70 حرفا 67 حرفا

الرموز ^ { } \ [ ] ~ | € يُحتسب كل منها حرفين في GSM. حرف عربي واحد يحوّل النص كله إلى UCS2، فالرسالة العربية من 71 حرفا جزءان.

اضبط scheduledAt لترسل لاحقا. تبقى الرسالة queued حتى ذلك الوقت. وإذا كان لمؤسستك نافذة إرسال في التفضيلات، تنتظر الرسائل خارجها حتى تُفتح.

{
"to": "+201001234567",
"body": "Reminder: your appointment is tomorrow at 09:30.",
"scheduledAt": "2026-11-20T07:00:00Z"
}