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

الحملات

يرسل 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

تنشئ مسودة. لا يرسل شيء حتى تستدعي 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 البدء لاحقًا (حتى سنة مقدمًا) بدل البدء فورًا.
create-campaign.ts
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 يضاف إلى قائمتك السوداء ويستبعد من كل حملة لاحقة.

الحملات، الأحدث أولًا، مع progress المباشر لكل منها. صفّ حسب status.

running-campaigns.ts
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.

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

تغيّر أي حقل من حقول الإنشاء. للمسودات فقط: أي حالة أخرى تعيد 409 invalid_campaign_state.

update-campaign.ts
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-campaign.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
await sms.campaigns.delete('cmp_…');

ما ستفعله الحملة قبل أن تبدأها: عدد المستلمين بعد استبعاد الملغى اشتراكهم والقائمة السوداء، وإجمالي الأجزاء، وسعة الهواتف، والمعدل الفعلي، وعدد من ينتظرون انتهاء ساعات الهدوء، والمدة المتوقعة، والتحذيرات warnings (empty_audience وno_devices وcapacity_below_throttle وunreachable_recipients وmulti_zone_countries). تعمل على المسودات والحملات المجدولة.

estimate.ts
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.

start.ts
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 استلام مستلمين جدد؛ والرسائل التي وصلت إلى هاتف بالفعل تخرج كالمعتاد. وتستأنف resume الإرسال، ويبدأ ضبط المعدل من تلك اللحظة، فلا يحدث اندفاع مفاجئ.

pause-resume.ts
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_…');

تنهي حملة مجدولة أو جارية أو موقوفة نهائيًا. تتخطى الحملة المستلمين المعلقين وتسجل السبب canceled، وتحظر الرسائل التي لم يستلمها أي هاتف بعد مع errorCode: 'campaign_canceled'. لا يمكن التراجع عن الإلغاء.

cancel.ts
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 …

الصورة النهائية: المتجاوزون حسب السبب (blacklisted وopted_out وcanceled وcontact_deleted وinvalid_number وbody_too_long)، والإخفاقات حسب رمز الخطأ، والأعداد لكل هاتف وشريحة، والمدة الفعلية، ومدى ابتعادها عن التقدير، ونسبة التسليم.

report.ts
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 }).