وصفات جاهزة
كل وصفة ملف كامل يمكنك نسخه. تقرأ الوصفات مفتاح API من SMSFABRIC_API_KEY؛ ابدأ بمفتاح sf_test_ حتى لا يصل شيء إلى هاتف حقيقي.
مستقبل خطافات ويب باستخدام Express
Section titled “مستقبل خطافات ويب باستخدام Express”مستقبل يتحقق من التوقيع على المحتوى الخام، ويرد ضمن حد الثواني العشر، ويتجاهل التسليمات المكررة، ثم يعالج الحدث. ثبّت express إلى جانب الحزمة.
import express from 'express';import { SMSFabric, SignatureVerificationError, type WebhookPayload } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const secret = process.env.SMSFABRIC_WEBHOOK_SECRET ?? '';const app = express();
// Keep a durable store in production (a table with a unique key on the event id).const seen = new Set<string>();
app.post('/hooks/smsfabric', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => { let event: WebhookPayload; try { event = sms.webhooks.constructEvent(req.body, req.header('SMSFabric-Signature'), secret); } catch (err) { if (err instanceof SignatureVerificationError) return res.sendStatus(400); throw err; }
res.sendStatus(200); // answer first, work afterwards if (seen.has(event.id)) return; seen.add(event.id);
handle(event).catch((err: unknown) => console.error('webhook handler failed', event.id, err));});
async function handle(event: WebhookPayload): Promise<void> { switch (event.type) { case 'message.delivered': case 'message.failed': console.log(event.type, event.data['id'], event.data['errorCode'] ?? ''); break; case 'message.received': console.log('Inbound from', event.data['from'], ':', event.data['body']); break; default: console.log('Ignored', event.type); }}
app.use(express.json()); // other routes; the webhook route above keeps the raw bodyapp.listen(3000, () => console.log('Listening on :3000'));سجّله عبر webhooks.create وأرسل حدث اختبار عبر webhooks.test. لإتاحة خادم محلي أثناء التطوير، استخدم نفقًا بعنوان https.
تسجيل الدخول برمز تحقق
Section titled “تسجيل الدخول برمز تحقق”دالتان لتسجيل الدخول برقم الهاتف: ترسل startSignIn رمزًا وتعيد معرف التحقق لتحفظه مع محاولة الدخول، وتفحص finishSignIn الرمز الذي كتبه المستخدم. حالات الرفض تتحول إلى رسائل يمكنك عرضها.
import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY }); // scopes: verify:send, verify:check
export type StartResult = { ok: true; verificationId: string; expiresAt: string } | { ok: false; reason: string; retryAfterSec?: number };export type FinishResult = { ok: true } | { ok: false; reason: string; attemptsLeft?: number };
export async function startSignIn(phone: string, locale: 'en' | 'ar' = 'en'): Promise<StartResult> { try { const v = await sms.verifications.send({ to: phone, locale }); return { ok: true, verificationId: v.id, expiresAt: v.expiresAt }; } catch (err) { if (!(err instanceof SMSFabricError)) throw err; switch (err.code) { case 'validation_failed': return { ok: false, reason: 'Enter the number with its country code, like +201001234567.' }; case 'verify_resend_limited': case 'verify_velocity_exceeded': return { ok: false, reason: 'Too many codes requested. Try again shortly.', retryAfterSec: 600 }; case 'verify_country_not_allowed': return { ok: false, reason: 'We cannot send codes to this country yet.' }; case 'verify_prefix_blocked': case 'verify_recipient_blacklisted': return { ok: false, reason: 'We cannot send a code to this number.' }; default: throw err; } }}
export async function finishSignIn(verificationId: string, code: string): Promise<FinishResult> { if (!/^\d{4,10}$/.test(code)) return { ok: false, reason: 'Enter the digits from the SMS.' }; try { const result = await sms.verifications.check(verificationId, code); switch (result.status) { case 'approved': return { ok: true }; case 'pending': return { ok: false, reason: 'That code is not right.', attemptsLeft: result.attemptsLeft }; default: return { ok: false, reason: 'This code can no longer be used. Request a new one.' }; } } catch (err) { if (err instanceof SMSFabricError && err.code === 'verification_already_approved') return { ok: true }; throw err; }}اربط معرف التحقق بجلسة المستخدم على خادمك، لا بقيمة يرسلها المتصفح وحده، ولا تنشئ الجلسة إلا بعد أن تعيد finishSignIn القيمة ok: true. التفاصيل في دليل التحقق.
إرسال جماعي مقسم مع منع التكرار
Section titled “إرسال جماعي مقسم مع منع التكرار”تقبل messages.send حتى 100 مستلم في الاستدعاء الواحد. يقسم هذا السكربت القائمة إلى دفعات من 100، ويمنح كل دفعة مفتاح منع تكرار مشتقًا من اسم الإرسال ورقم الدفعة. إذا انهار السكربت ثم عمل مجددًا، فالدفعات التي أرسلت تعيد استجاباتها المحفوظة بدل الإرسال مرة أخرى.
import { SMSFabric, SMSFabricError, type Message } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const CHUNK = 100;
function chunk<T>(items: T[], size: number): T[][] { const out: T[][] = []; for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size)); return out;}
export async function bulkSend(batchId: string, recipients: string[], body: string): Promise<Message[]> { const unique = [...new Set(recipients)]; const sent: Message[] = []; for (const [i, to] of chunk(unique, CHUNK).entries()) { try { const messages = await sms.messages.send({ to, body, metadata: { batchId } }, { idempotencyKey: `${batchId}:${i}` }); sent.push(...messages); } catch (err) { if (err instanceof SMSFabricError) console.error(`Chunk ${i} failed: ${err.status} ${err.code}`, err.requestId); throw err; // stop, fix, run again: finished chunks are not sent twice } } return sent;}
const result = await bulkSend('promo-2026-11-21', ['+201001234567', '+201001234568'], 'Our Giza branch opens on Saturday. Reply STOP to opt out.');const blocked = result.filter((m) => m.status === 'blocked').length;console.log(`${result.length} accepted, ${blocked} blocked by the blacklist`);أبق قائمة المستلمين وحجم الدفعة ثابتين بين التشغيلات: المفتاح نفسه مع محتوى مختلف يعيد 422 idempotency_key_reused. وتحفظ مفاتيح منع التكرار 24 ساعة.
أرسل وانتظر التسليم
Section titled “أرسل وانتظر التسليم”خطافات الويب هي الطريقة الصحيحة لمعرفة التسليم في بيئة الإنتاج. أما في سكربت أو اختبار أو فحص لمرة واحدة، فاستعلم عبر messages.get حتى تصل الرسالة إلى حالة نهائية:
import { setTimeout as sleep } from 'node:timers/promises';import { SMSFabric, type MessageStatus, type MessageWithEvents } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const FINAL: ReadonlySet<MessageStatus> = new Set<MessageStatus>(['delivered', 'failed', 'blocked']);
export async function waitForDelivery(id: string, timeoutMs = 120_000): Promise<MessageWithEvents> { const deadline = Date.now() + timeoutMs; let delay = 1_000; for (;;) { const message = await sms.messages.get(id); if (FINAL.has(message.status)) return message; if (Date.now() + delay > deadline) throw new Error(`Message ${id} is still ${message.status} after ${timeoutMs} ms`); await sleep(delay); delay = Math.min(delay * 2, 10_000); }}
const [message] = await sms.messages.send({ to: '+201001234567', body: 'Delivery check' });if (message) { const final = await waitForDelivery(message.id); console.log(final.status, final.errorCode ?? '', final.events.map((e) => e.type).join(' → '));}تعني sent أن شبكة الاتصالات قبلت الرسالة؛ أما delivered فتحتاج إلى تقرير تسليم من الهاتف المستقبل، وبعض الشبكات لا ترسله أبدًا. اعتبر الرسالة التي تبقى sent مرسلة، لا فاشلة.