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

سطر الأوامر

ينفذ الأمر 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

أداة سطر الأوامر غير منشورة على npm بعد. ابنها من مستودع SMSFabric ثم شغّل الملف المبني. تحتاج إلى Node.js 20 أو أحدث وإلى pnpm.

نافذة طرفيّة
pnpm install
pnpm --filter @smsfabric/cli... build
node packages/cli/dist/bin.js --help

تكتب الأمثلة في هذه الصفحة smsfabric بدلا من node packages/cli/dist/bin.js.

تقرأ الأداة مفتاح API من SMSFABRIC_API_KEY وحده. لا يوجد خيار --api-key، فلا يظهر المفتاح أبدا في سجل الطرفية ولا في قائمة العمليات.

مع مفتاح تجريبي (sf_test_…) تذهب كل رسالة إلى الجهاز الافتراضي: تحصل على الواجهة البرمجية كاملة وعلى أحداث حقيقية، ولا تخرج أي رسالة من أي هاتف. راجع بيئة الاختبار.

نافذة طرفيّة
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/sms
Listening 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.

اضبط SMSFABRIC_WEBHOOK_SECRET على السر الذي يتحقق به تطبيقك، فيوقع listen به. وبدونه ينشئ listen سرا لهذا التشغيل ويطبعه مرة واحدة: أعط هذه القيمة لتطبيقك.

listen مخصص للتطوير.

  • الأحداث التي تقع وهو غير متصل لا يعاد إرسالها.
  • الإرسال الذي يفشل يُعرض ولا يعاد.
  • يمكن أن يتصل بالمؤسسة 5 مستمعين في وقت واحد.

أما في الإنتاج فـسجّل نقطة نهاية. تحصل على إعادة المحاولة لنحو 24 ساعة وعلى سجل للطلبات.

الرمز المعنى
0 تم. في send: قُبلت كل الرسائل.
1 رفضت الواجهة البرمجية الطلب، أو فشلت الشبكة، أو كان أحد المستلمين محظورا.
2 كُتب الأمر بشكل خاطئ، أو لم يُضبط SMSFABRIC_API_KEY.
المتغير المعنى
SMSFABRIC_API_KEY مطلوب. sf_test_… أو sf_live_….
SMSFABRIC_BASE_URL عنوان الواجهة البرمجية. يجب أن يكون https، إلا مع localhost.
SMSFABRIC_WEBHOOK_SECRET السر الذي يوقع به listen الأحداث المرسلة.