الحملات
يرسل sms.campaigns نصًا واحدًا أو قالبًا إلى جهات الاتصال في مجموعات معينة أو التي تحمل وسومًا معينة، أو كليهما. تصل الرسالة إلى كل جهة اتصال مرة واحدة، وتستبعد الأرقام الملغى اشتراكها والموجودة في القائمة السوداء. القراءة تحتاج إلى campaigns:read، والتعديل إلى campaigns:manage، والبدء يحتاج أيضًا إلى messages:send. المفاهيم في دليل الحملات.
تنتقل الحملة بين الحالات draft ← scheduled ← running ⇄ paused ← completed، ويمكن أن تصبح canceled من scheduled أو running أو paused.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
create(params, options?) |
POST /v1/campaigns |
Campaign |
list(params?) |
GET /v1/campaigns |
Paginated<Campaign> |
listAll(params?) |
GET /v1/campaigns (كل الصفحات) |
AsyncGenerator<Campaign> |
get(id) |
GET /v1/campaigns/:id |
Campaign |
update(id, params) |
PATCH /v1/campaigns/:id |
Campaign |
delete(id) |
DELETE /v1/campaigns/:id |
void |
estimate(id) |
POST /v1/campaigns/:id/estimate |
CampaignEstimate |
start(id) |
POST /v1/campaigns/:id/start |
Campaign |
pause(id) |
POST /v1/campaigns/:id/pause |
Campaign |
resume(id) |
POST /v1/campaigns/:id/resume |
Campaign |
cancel(id) |
POST /v1/campaigns/:id/cancel |
Campaign |
report(id) |
GET /v1/campaigns/:id/report |
CampaignReport |
create
Section titled “create”تنشئ مسودة. لا يرسل شيء حتى تستدعي start.
| المعامل | النوع | ملاحظات |
|---|---|---|
name |
string |
مطلوب. |
groupIds |
string[] |
حتى 20 مجموعة. |
tags |
string[] |
حتى 20 وسمًا. تدخل جهة الاتصال في الجمهور إذا كانت في أي من المجموعات أو تحمل أيًا من الوسوم. |
templateId أو body |
string |
أحدهما. يمكن أن يستخدم النص {{first_name}} و{{last_name}} و{{custom.<key>}}. |
poolId، أو deviceId وsimId |
string |
المسار، وليس كليهما. الافتراضي: الشريحة الافتراضية للمؤسسة. |
ratePerMinute |
number |
من 1 إلى 6,000 رسالة في الدقيقة للحملة كلها. الافتراضي 120. |
hourlyCap |
number | null |
أقصى عدد من المستلمين في الساعة حسب timeZone (من 1 إلى 360,000). |
dailyCap |
number | null |
أقصى عدد من المستلمين في اليوم حسب timeZone (من 1 إلى 8,640,000)، ولا يقل عن hourlyCap. |
quietHours |
{ start, end } | null |
بصيغة HH:MM حسب التوقيت المحلي لكل مستلم، ويمكن أن تتجاوز منتصف الليل، مثل 21:00 إلى 09:00. |
timeZone |
string |
منطقة IANA للأرقام التي لا تعرف دولتها. الافتراضي: timeZone في تفضيلاتك. |
scheduledAt |
Date | string | null |
البدء لاحقًا (حتى سنة مقدمًا) بدل البدء فورًا. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const campaign = await sms.campaigns.create({ name: 'November offers', groupIds: ['grp_…'], tags: ['vip'], body: 'Hi {{first_name|there}}, 20% off this weekend. Reply STOP to opt out.', poolId: 'pool_…', ratePerMinute: 60, quietHours: { start: '21:00', end: '09:00' },});console.log(campaign.id, campaign.status); // cmp_… draftأضف عبارة إلغاء الاشتراك. المستلم الذي يرد بـ STOP يضاف إلى قائمتك السوداء ويستبعد من كل حملة لاحقة.
list and listAll
Section titled “list and listAll”الحملات، الأحدث أولًا، مع progress المباشر لكل منها. صفّ حسب status.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
for await (const c of sms.campaigns.listAll({ status: 'running' })) { console.log(c.name, `${c.progress.sent}/${c.progress.recipients}`, 'ETA', c.progress.etaAt);}حملة واحدة. يحتوي progress على recipients وpending وqueued وsent وdelivered وfailed وskipped وratePerMinute المقاس (آخر 30 ثانية) وetaAt.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const c = await sms.campaigns.get('cmp_…');console.log(c.status, c.progress);update
Section titled “update”تغيّر أي حقل من حقول الإنشاء. للمسودات فقط: أي حالة أخرى تعيد 409 invalid_campaign_state.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.update('cmp_…', { ratePerMinute: 30, scheduledAt: new Date('2026-11-21T08:00:00Z') });delete
Section titled “delete”تحذف مسودة. أما الحملة التي بدأت فيمكن إلغاؤها.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.delete('cmp_…');estimate
Section titled “estimate”ما ستفعله الحملة قبل أن تبدأها: عدد المستلمين بعد استبعاد الملغى اشتراكهم والقائمة السوداء، وإجمالي الأجزاء، وسعة الهواتف، والمعدل الفعلي، وعدد من ينتظرون انتهاء ساعات الهدوء، والمدة المتوقعة، والتحذيرات warnings (empty_audience وno_devices وcapacity_below_throttle وunreachable_recipients وmulti_zone_countries). تعمل على المسودات والحملات المجدولة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const e = await sms.campaigns.estimate('cmp_…');console.log(`${e.recipients} recipients, ${e.segments} segments, ${e.effectiveRatePerMinute}/min`);console.log('Excluded:', e.excluded, 'Done by', e.completesAt ?? 'never (see warnings)');if (e.warnings.length) console.warn(e.warnings);تبدأ المسودة الآن، أو تجدولها إذا كان scheduledAt في المستقبل. مع مفتاح sf_test_ تعمل الحملة في بيئة الاختبار. الجمهور الفارغ يعيد 422 campaign_audience_empty.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const estimate = await sms.campaigns.estimate('cmp_…');if (estimate.warnings.length === 0 && estimate.recipients <= 5_000) { const c = await sms.campaigns.start('cmp_…'); console.log(c.status); // running or scheduled}pause and resume
Section titled “pause and resume”توقف pause استلام مستلمين جدد؛ والرسائل التي وصلت إلى هاتف بالفعل تخرج كالمعتاد. وتستأنف resume الإرسال، ويبدأ ضبط المعدل من تلك اللحظة، فلا يحدث اندفاع مفاجئ.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.pause('cmp_…');// …fix the problem…await sms.campaigns.resume('cmp_…');cancel
Section titled “cancel”تنهي حملة مجدولة أو جارية أو موقوفة نهائيًا. تتخطى الحملة المستلمين المعلقين وتسجل السبب canceled، وتحظر الرسائل التي لم يستلمها أي هاتف بعد مع errorCode: 'campaign_canceled'. لا يمكن التراجع عن الإلغاء.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const c = await sms.campaigns.cancel('cmp_…');console.log(c.status, c.progress.skipped); // canceled …report
Section titled “report”الصورة النهائية: المتجاوزون حسب السبب (blacklisted وopted_out وcanceled وcontact_deleted وinvalid_number وbody_too_long)، والإخفاقات حسب رمز الخطأ، والأعداد لكل هاتف وشريحة، والمدة الفعلية، ومدى ابتعادها عن التقدير، ونسبة التسليم.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const r = await sms.campaigns.report('cmp_…');console.log('Delivery rate', r.deliveryRate, 'skipped', r.skipped, 'failures', r.failures);for (const row of r.byDevice) console.log(row.deviceName, row.sent, row.delivered, row.failed);كل رسالة ترسلها حملة هي رسالة عادية تحمل metadata.campaignId، فيعرضها sms.messages.list({ campaignId }).