إرسال الرسائل
تضع POST /v1/messages نصا في الطابور لمستلم واحد أو حتى 100 مستلم. ترد الواجهة فورا بالحالة 201 Created ورسالة لكل مستلم. بعدها يستلم أحد الهواتف الرسالة ويرسلها، وتتابعها أنت عبر التتبع وwebhooks.
إرسال رسالة واحدة
Section titled “إرسال رسالة واحدة”يحتاج المفتاح إلى الصلاحية 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" } }'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const [message] = await sf.messages.send( { to: '+201001234567', body: 'Your order #1042 has shipped. Track it at acme.example/t/1042', metadata: { orderId: '1042' }, }, { idempotencyKey: 'order-1042-shipped' },);console.log(message.id, message.status); // msg_… queuedimport osimport requests
res = requests.post( "https://api.smsfabric.com/v1/messages", headers={ "X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "order-1042-shipped", }, json={ "to": "+201001234567", "body": "Your order #1042 has shipped. Track it at acme.example/t/1042", "metadata": {"orderId": "1042"}, }, timeout=30,)res.raise_for_status()message = res.json()["data"][0]print(message["id"], message["status"])<?php$payload = json_encode([ 'to' => '+201001234567', 'body' => 'Your order #1042 has shipped. Track it at acme.example/t/1042', 'metadata' => ['orderId' => '1042'],]);$ch = curl_init('https://api.smsfabric.com/v1/messages');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload, CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: order-1042-shipped', ], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$message = json_decode(curl_exec($ch), true)['data'][0];echo $message['id'] . ' ' . $message['status'] . "\n";الاستجابة:
{ "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 بعد توجيه الرسالة إلى هاتف.
حقول الطلب
Section titled “حقول الطلب”| الحقل | النوع | إلزامي | الوصف |
|---|---|---|---|
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>]، ولا يُرسل شيء.
الإرسال إلى عدة أرقام
Section titled “الإرسال إلى عدة أرقام”مرّر مصفوفة. تحصل على رسالة لكل مستلم بالترتيب نفسه، لكل منها id وحالة خاصة بها.
{ "to": ["+201001234567", "+201001234568", "+966501234567"], "body": "The Nasr City branch opens at 10:00 tomorrow."}الرقم الموجود في القائمة السوداء لا يُفشل الطلب. تعود رسالته بالحالة status: "blocked" وerrorCode: "blacklisted" ولا تغادر الخادم، وتدخل الرسائل الأخرى الطابور.
لأكثر من 100 مستلم أو لنص مخصص لكل شخص، استخدم حملة.
اختيار الهاتف
Section titled “اختيار الهاتف”إذا لم ترسل حقول توجيه، تختار SMSFabric الهاتف بهذا الترتيب:
simIdأوdeviceIdإن أرسلت أحدهما.poolId: بالتناوب على هواتف المجموعة المتصلة.- الشريحة الافتراضية للمؤسسة (تُضبط من الأجهزة أو عبر
POST /v1/devices/:id/sims/:simId/default). - بالتناوب على كل الهواتف المتصلة.
إذا لم يكن أي هاتف متصلا، يُوقظ آخر هاتف ظهر عبر إشعار وتنتظره الرسالة. وإذا لم يستطع أي هاتف استلامها إطلاقا تفشل مع errorCode: "no_device_available".
الإرسال مع poolId يضيف التحويل عند التعطل: إذا لم يقبل الهاتف الرسالة خلال 10 ثوان، أو رفضها، أو انقطع اتصاله، تنتقل الرسالة إلى هاتف متصل آخر في المجموعة. وعندما يبلّغ الهاتف عن فشل الإرسال، تُعاد المحاولة حتى maxRetries مرة (2 افتراضيا، في التفضيلات)، على هاتف آخر في المجموعة إن وجد، وإلا على الهاتف نفسه.
يلتزم كل هاتف بفترة انتظار بين الرسائل (3 ثوان افتراضيا مع تفاوت عشوائي حتى ثانيتين) لحماية شرائحك. خطط للسرعة على هذا الأساس: يرسل الهاتف الواحد نحو 14 رسالة في الدقيقة بالإعدادات الافتراضية. أضف هواتف إلى مجموعة لتسرع.
الأجزاء والترميز
Section titled “الأجزاء والترميز”تبيّن الواجهة كيف ستحتسب شركة الاتصالات النص:
| الترميز | يُستخدم عندما | جزء واحد | كل جزء من نص أطول |
|---|---|---|---|
GSM7 |
كل الأحرف من أبجدية GSM 03.38 | 160 حرفا | 153 حرفا |
UCS2 |
أي حرف آخر، ومنه العربية والرموز التعبيرية | 70 حرفا | 67 حرفا |
الرموز ^ { } \ [ ] ~ | € يُحتسب كل منها حرفين في GSM. حرف عربي واحد يحوّل النص كله إلى UCS2، فالرسالة العربية من 71 حرفا جزءان.
جدولة رسالة
Section titled “جدولة رسالة”اضبط scheduledAt لترسل لاحقا. تبقى الرسالة queued حتى ذلك الوقت. وإذا كان لمؤسستك نافذة إرسال في التفضيلات، تنتظر الرسائل خارجها حتى تُفتح.
{ "to": "+201001234567", "body": "Reminder: your appointment is tomorrow at 09:30.", "scheduledAt": "2026-11-20T07:00:00Z"}الخطوات التالية
Section titled “الخطوات التالية”- تتبّع التسليم عبر
GET /v1/messages/:idوwebhooks. - استقبل الردود.
- قائمة الحقول الكاملة في مرجع الرسائل.