الرسائل
يرسل sms.messages الرسائل عبر هواتف البوابة ويقرأ ما أرسل وما استقبل. الإرسال يحتاج إلى النطاق messages:send، والقراءة إلى messages:read، وتصدير CSV إلى logs:export.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
send(params, options?) |
POST /v1/messages |
Message[] |
list(params?) |
GET /v1/messages |
Paginated<Message> |
listAll(params?) |
GET /v1/messages (كل الصفحات) |
AsyncGenerator<Message> |
get(id) |
GET /v1/messages/:id |
MessageWithEvents |
stats(params?) |
GET /v1/messages/stats |
MessageStats |
exportCsv(params?) |
GET /v1/messages/export.csv |
string |
ترسل نصًا واحدًا إلى مستلم واحد أو إلى 100 مستلم كحد أقصى. تعيد كائن Message لكل مستلم بالترتيب نفسه، بالحالة queued، أو blocked للرقم الموجود في قائمتك السوداء.
| المعامل | النوع | ملاحظات |
|---|---|---|
to |
string | string[] |
أرقام بصيغة E.164، حتى 100 رقم. |
body |
string |
حتى 1,600 حرف. النص الطويل يرسل على عدة أجزاء. |
deviceId |
string |
الإرسال من هذا الهاتف. |
simId |
string |
الإرسال من هذه الشريحة. |
poolId |
string |
توزيع دوري على هواتف المجموعة المتصلة، مع التحويل عند التعطل. |
scheduledAt |
Date | string |
الإرسال في وقت لاحق. |
metadata |
Record<string, unknown> |
بياناتك الخاصة، تعود مع الرسالة وفي خطافات الويب الخاصة بها. |
إذا لم تحدد مسارًا، تخرج الرسالة عبر الشريحة الافتراضية للمؤسسة. يقبل الوسيط الثاني idempotencyKey؛ راجع منع التكرار.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const messages = await sms.messages.send( { to: ['+201001234567', '+201001234568'], body: 'The clinic is closed on Friday. Reply STOP to opt out.', poolId: 'pool_…', metadata: { notice: 'friday-closure' }, }, { idempotencyKey: 'friday-closure-2026-11-20' },);
for (const m of messages) console.log(m.id, m.to, m.status, m.segments);صفحة واحدة من الرسائل، الأحدث أولًا. صفّ حسب direction (outbound أو inbound) وstatus وdeviceId وcampaignId وq (رقم هاتف) ونطاق تاريخ from / to. قيمة limit من 1 إلى 200 (الافتراضية 50)؛ ومرّر nextCursor المعاد في cursor لجلب الصفحة التالية.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.messages.list({ status: 'failed', from: new Date(Date.now() - 24 * 60 * 60 * 1000), limit: 100,});
for (const m of page.data) console.log(m.createdAt, m.to, m.errorCode);if (page.nextCursor) console.log('More with cursor', page.nextCursor);listAll
Section titled “listAll”المرشحات نفسها التي تقبلها list دون cursor. تتتبع كل المؤشرات وتعيد رسالة واحدة في كل مرة، فيمكنك التوقف مبكرًا بـ break.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });const midnight = new Date();midnight.setUTCHours(0, 0, 0, 0);
for await (const m of sms.messages.listAll({ direction: 'inbound', from: midnight })) { console.log(m.from, m.body);}رسالة واحدة مع سجل تسليمها في events: الانتظار والتوجيه والإرسال والتسليم أو الفشل، مع الهاتف الذي نفذ كل خطوة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const message = await sms.messages.get('msg_…');console.log(message.status, message.deliveredAt);for (const e of message.events) console.log(e.createdAt, e.type, e.status);رموز التحقق المرسلة عبر التحقق رسائل أيضًا، لكن body فيها يظهر دائمًا [verification code hidden].
أعداد sent وdelivered وfailed لكل يوم خلال آخر days يومًا بتوقيت UTC (من 1 إلى 31، الافتراضي 7) حتى اليوم، مع الإجماليات.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const stats = await sms.messages.stats({ days: 14 });for (const day of stats.days) console.log(day.date, day.sent, day.delivered, day.failed);console.log('Queued now:', stats.totals.queued);exportCsv
Section titled “exportCsv”المرشحات نفسها التي تقبلها list (دون limit وcursor)، والنتيجة نص CSV. تعالج الخلايا بحيث لا ينفذ برنامج الجداول أيًا منها كصيغة. يحتاج إلى logs:export.
import { writeFile } from 'node:fs/promises';import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const csv = await sms.messages.exportCsv({ campaignId: 'cmp_…' });await writeFile('campaign-messages.csv', csv);يحتوي الملف المصدّر على أرقام الهواتف ونصوص الرسائل. احفظه بالعناية نفسها التي تحمي بها البيانات في البوابة.