سطر الأوامر
ينفذ الأمر smsfabric مهمتين من الطرفية:
smsfabric sendيرسل رسالة SMS.smsfabric listenيعرض أحداث webhook لحظة وقوعها ويرسلها إلى خادم على جهازك، دون عنوان عام ودون نفق.
export SMSFABRIC_API_KEY="sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"smsfabric send --to +201001234567 --body "Your order is out for delivery."smsfabric listen --forward-to http://localhost:3000/hooks/smsالتثبيت
Section titled “التثبيت”أداة سطر الأوامر غير منشورة على npm بعد. ابنها من مستودع SMSFabric ثم شغّل الملف المبني. تحتاج إلى Node.js 20 أو أحدث وإلى pnpm.
pnpm installpnpm --filter @smsfabric/cli... buildnode packages/cli/dist/bin.js --helpتكتب الأمثلة في هذه الصفحة smsfabric بدلا من node packages/cli/dist/bin.js.
المصادقة
Section titled “المصادقة”تقرأ الأداة مفتاح API من SMSFABRIC_API_KEY وحده. لا يوجد خيار --api-key، فلا يظهر المفتاح أبدا في سجل الطرفية ولا في قائمة العمليات.
مع مفتاح تجريبي (sf_test_…) تذهب كل رسالة إلى الجهاز الافتراضي: تحصل على الواجهة البرمجية كاملة وعلى أحداث حقيقية، ولا تخرج أي رسالة من أي هاتف. راجع بيئة الاختبار.
إرسال رسالة SMS
Section titled “إرسال رسالة SMS”smsfabric send --to +201001234567 --body "Your code is 4821"تطبع الأداة سطرا لكل رسالة، فيه معرفها وحالتها والمستلم:
msg_k2v8x0q4n1 queued +201001234567| الخيار | المعنى |
|---|---|
--to <number> |
المستلم بصيغة E.164. كرره لما يصل إلى 100 مستلم. |
--body <text> |
نص الرسالة. |
--device <id> |
أرسل من هذا الهاتف (dev_…). |
--sim <id> |
أرسل من هذه الشريحة (sim_…). |
--pool <id> |
أرسل عبر هذه المجموعة (pool_…). |
--at <time> |
جدول الرسالة لوقت بصيغة ISO 8601، مثل 2026-12-01T09:00:00Z. |
--idempotency-key <key> |
استخدم المفتاح نفسه لإعادة المحاولة دون إرسال مرتين. بدونه يحصل كل تشغيل على مفتاح جديد. راجع منع التكرار. |
--json |
اطبع استجابة الواجهة البرمجية بصيغة JSON. |
--base-url <url> |
عنوان الواجهة البرمجية. الافتراضي: SMSFABRIC_BASE_URL ثم https://api.smsfabric.com. |
يحتاج المفتاح إلى الصلاحية messages:send.
استقبال أحداث webhook محليا
Section titled “استقبال أحداث webhook محليا”smsfabric listen --forward-to http://localhost:3000/hooks/sms --events message.delivered,message.failedيطبع listen كل حدث webhook في مؤسستك لحظة وقوعه. ومع --forward-to يرسل كل حدث أيضا إلى خادمك، بالمحتوى نفسه وبترويستي SMSFabric-Signature وSMSFabric-Event-Id نفسيهما كما في webhook حقيقي. فيعمل التحقق من التوقيع في معالجك دون أي تغيير.
Signing secret for this run: whsec_…Forwarding to http://localhost:3000/hooks/smsListening for message.delivered, message.failed. Press Ctrl+C to stop.12:00:04 message.delivered evt_x1c9… -> 204 (12 ms)| الخيار | المعنى |
|---|---|
--forward-to <url> |
العنوان الذي تُرسل إليه الأحداث. يجب أن يكون على هذا الجهاز ما لم تضف --allow-remote. |
--events <list> |
أنواع الأحداث مفصولة بفواصل. الافتراضي: كل الأحداث. |
--allow-remote |
اسمح بعنوان على جهاز آخر. قد تحتوي الأحداث على نص الرسائل، فاستخدمه مع خادم تثق به فقط. |
--json |
اطبع محتوى JSON الكامل لكل حدث على stdout لتمريره إلى jq. تذهب أسطر الحالة إلى stderr. |
--base-url <url> |
عنوان الواجهة البرمجية. |
يحتاج المفتاح إلى الصلاحية webhooks:manage.
سر التوقيع
Section titled “سر التوقيع”اضبط SMSFABRIC_WEBHOOK_SECRET على السر الذي يتحقق به تطبيقك، فيوقع listen به. وبدونه ينشئ listen سرا لهذا التشغيل ويطبعه مرة واحدة: أعط هذه القيمة لتطبيقك.
الحدود
Section titled “الحدود”listen مخصص للتطوير.
- الأحداث التي تقع وهو غير متصل لا يعاد إرسالها.
- الإرسال الذي يفشل يُعرض ولا يعاد.
- يمكن أن يتصل بالمؤسسة 5 مستمعين في وقت واحد.
أما في الإنتاج فـسجّل نقطة نهاية. تحصل على إعادة المحاولة لنحو 24 ساعة وعلى سجل للطلبات.
رموز الخروج
Section titled “رموز الخروج”| الرمز | المعنى |
|---|---|
0 |
تم. في send: قُبلت كل الرسائل. |
1 |
رفضت الواجهة البرمجية الطلب، أو فشلت الشبكة، أو كان أحد المستلمين محظورا. |
2 |
كُتب الأمر بشكل خاطئ، أو لم يُضبط SMSFABRIC_API_KEY. |
متغيرات البيئة
Section titled “متغيرات البيئة”| المتغير | المعنى |
|---|---|
SMSFABRIC_API_KEY |
مطلوب. sf_test_… أو sf_live_…. |
SMSFABRIC_BASE_URL |
عنوان الواجهة البرمجية. يجب أن يكون https، إلا مع localhost. |
SMSFABRIC_WEBHOOK_SECRET |
السر الذي يوقع به listen الأحداث المرسلة. |