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

الرسائل

يرسل 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؛ راجع منع التكرار.

send.ts
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 لجلب الصفحة التالية.

list-failed.ts
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);

المرشحات نفسها التي تقبلها list دون cursor. تتتبع كل المؤشرات وتعيد رسالة واحدة في كل مرة، فيمكنك التوقف مبكرًا بـ break.

inbound-today.ts
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: الانتظار والتوجيه والإرسال والتسليم أو الفشل، مع الهاتف الذي نفذ كل خطوة.

get.ts
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) حتى اليوم، مع الإجماليات.

stats.ts
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);

المرشحات نفسها التي تقبلها list (دون limit وcursor)، والنتيجة نص CSV. تعالج الخلايا بحيث لا ينفذ برنامج الجداول أيًا منها كصيغة. يحتاج إلى logs:export.

export.ts
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);

يحتوي الملف المصدّر على أرقام الهواتف ونصوص الرسائل. احفظه بالعناية نفسها التي تحمي بها البيانات في البوابة.