تشغيل حملة
ترسل الحملة رسالة واحدة إلى عدد كبير من جهات الاتصال. تأخذ SMSFabric لقطة من الجمهور، وتستبعد الأرقام الملغية للاشتراك والموجودة في القائمة السوداء، وتملأ متغيرات كل جهة اتصال، ثم تمرر الرسائل إلى هواتفك بالسرعة التي تحتملها. استخدمها بدل حلقة على POST /v1/messages كلما كان لديك أكثر من بضعة مستلمين.
قبل أن تبدأ
Section titled “قبل أن تبدأ”تحتاج إلى:
- جهات اتصال في مجموعات أو بوسوم. أنشئها عبر
POST /v1/contactsأو استورد ملف CSV عبرPOST /v1/contact-imports(انظر مرجع الاستيراد). - مفتاح بالصلاحيتين
campaigns:manageوmessages:send(وcontacts:manageلإضافة جهات الاتصال). - هاتف متصل واحد على الأقل، إلا إذا كنت تختبر بمفتاح
sf_test_.
الخطوات
Section titled “الخطوات”- أنشئ مسودة عبر
POST /v1/campaigns. - افحصها عبر
POST /v1/campaigns/:id/estimate: المستلمون والأجزاء والمدة والتحذيرات. - ابدأها عبر
POST /v1/campaigns/:id/start. - تابع
progressعبرGET /v1/campaigns/:idأو webhookcampaign.completed، ثم اقرأGET /v1/campaigns/:id/report.
كتابة الرسالة
Section titled “كتابة الرسالة”أرسل body مباشرا، أو templateId من POST /v1/templates. يمكن لكليهما استخدام المتغيرات:
| المتغير | يُملأ بـ |
|---|---|
{{first_name}} |
الاسم الأول لجهة الاتصال |
{{last_name}} |
اسم العائلة |
{{custom.<key>}} |
حقل مخصص، مثل {{custom.branch}} |
{{first_name|there}} |
الاسم الأول، أو there إذا كان فارغا (قيمة بديلة حتى 60 حرفا) |
القيمة المفقودة دون بديل تظهر فارغة، وتُدمج المسافة المزدوجة الناتجة. أي شيء آخر بين الأقواس المزدوجة يُرفض مع 400 template_invalid. جرّب النص على جهة اتصال حقيقية عبر POST /v1/templates/preview قبل البدء.
الإنشاء والتقدير والبدء
Section titled “الإنشاء والتقدير والبدء”# 1. Create the draftcurl https://api.smsfabric.com/v1/campaigns \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: winter-sale-2026" \ -d '{ "name": "Winter sale", "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"], "tags": ["vip"], "body": "Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.", "ratePerMinute": 60, "quietHours": { "start": "21:00", "end": "09:00" } }'
# 2. Estimatecurl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \ -H "X-Api-Key: $SMSFABRIC_API_KEY"
# 3. Startcurl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const draft = await sf.campaigns.create( { name: 'Winter sale', groupIds: ['grp_t6w9z2c5f8i1l4o7r0u3x6a9'], tags: ['vip'], body: 'Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.', ratePerMinute: 60, quietHours: { start: '21:00', end: '09:00' }, }, { idempotencyKey: 'winter-sale-2026' },);
const estimate = await sf.campaigns.estimate(draft.id);console.log(estimate.recipients, 'recipients,', estimate.warnings);
if (!estimate.warnings.includes('no_devices')) { const running = await sf.campaigns.start(draft.id); console.log(running.status); // running, or scheduled}import osimport requests
API = "https://api.smsfabric.com"headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}
draft = requests.post( f"{API}/v1/campaigns", headers={**headers, "Idempotency-Key": "winter-sale-2026"}, json={ "name": "Winter sale", "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"], "tags": ["vip"], "body": "Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.", "ratePerMinute": 60, "quietHours": {"start": "21:00", "end": "09:00"}, }, timeout=30,).json()
estimate = requests.post(f"{API}/v1/campaigns/{draft['id']}/estimate", headers=headers, timeout=30).json()print(estimate["recipients"], estimate["warnings"])
started = requests.post(f"{API}/v1/campaigns/{draft['id']}/start", headers=headers, timeout=30)started.raise_for_status()print(started.json()["status"])<?phpfunction sf(string $method, string $path, ?array $body = null, array $extra = []): array { $ch = curl_init('https://api.smsfabric.com' . $path); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => $method, CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body), CURLOPT_HTTPHEADER => array_merge(['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json'], $extra), CURLOPT_RETURNTRANSFER => true, ]); return json_decode(curl_exec($ch), true);}
$draft = sf('POST', '/v1/campaigns', [ 'name' => 'Winter sale', 'groupIds' => ['grp_t6w9z2c5f8i1l4o7r0u3x6a9'], 'tags' => ['vip'], 'body' => 'Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.', 'ratePerMinute' => 60, 'quietHours' => ['start' => '21:00', 'end' => '09:00'],], ['Idempotency-Key: winter-sale-2026']);
$estimate = sf('POST', "/v1/campaigns/{$draft['id']}/estimate");echo $estimate['recipients'] . " recipients\n";
$started = sf('POST', "/v1/campaigns/{$draft['id']}/start");echo $started['status'] . "\n";الجمهور
Section titled “الجمهور”تُجمع groupIds (حتى 20) وtags (حتى 20): جهة الاتصال الموجودة في أي من المجموعات أو التي تحمل أيا من الوسوم تدخل الجمهور مرة واحدة. عند البدء تأخذ SMSFabric لقطة وتتخطى:
- جهات الاتصال الملغية للاشتراك (ردت بكلمة STOP، أو عُلّمت
optedOut)، - الأرقام الموجودة في القائمة السوداء،
- الأرقام غير الصالحة، وجهات الاتصال التي تتجاوز رسالتها بعد ملء المتغيرات 1600 حرف.
البدء دون مستلمين يعيد 422 campaign_audience_empty. جهات الاتصال المضافة بعد البدء لا تُشمل.
السرعة وساعات الهدوء
Section titled “السرعة وساعات الهدوء”| الإعداد | الافتراضي | الأثر |
|---|---|---|
ratePerMinute |
120 | سقف للحملة كلها، من 1 إلى 6000. |
| الهواتف | يلتزم كل هاتف أيضا بفترة الانتظار والتفاوت الخاصين بالمؤسسة، وتُطبق الحدود اليومية للشرائح، وتتحول المجموعة عند التعطل. | |
quietHours |
لا شيء | { "start": "21:00", "end": "09:00" } بالتوقيت المحلي لكل مستلم، ويمكن أن تعبر منتصف الليل. |
timeZone |
المنطقة الزمنية لمؤسستك | تُستخدم للأرقام مجهولة الدولة. |
scheduledAt |
الآن | ابدأ لاحقا، حتى سنة مقدما. يعيد start عندها status: "scheduled". |
يُستمد التوقيت المحلي للمستلم من timeZone في جهة الاتصال، أو من دولة الرقم. في الدول ذات المناطق الزمنية المتعددة (US وCA وBR وRU وAU وMX…) تنتظر الحملة حتى تخرج كل مناطقها من ساعات الهدوء.
وجّه الحملة عبر poolId، أو deviceId وsimId، لا كليهما. دونها تستخدم التوجيه العادي (انظر إرسال الرسائل).
يخبرك التقدير بالسرعة الفعلية: effectiveRatePerMinute هي الأقل بين ratePerMinute وما تستطيع هواتفك إرساله. راقب warnings:
| التحذير | المعنى |
|---|---|
empty_audience |
لن يستلمها أحد. |
no_devices |
لا يوجد هاتف يستطيع الإرسال على هذا المسار. |
capacity_below_throttle |
هواتفك أبطأ من ratePerMinute. أضف هواتف إلى المجموعة، أو توقع مدة أطول. |
unreachable_recipients |
بهذه السرعة لن يصل بعض المستلمين خلال 14 يوما. |
multi_zone_countries |
بعض المستلمين في دول متعددة المناطق الزمنية. |
التحكم في حملة جارية
Section titled “التحكم في حملة جارية”| الطلب | من | إلى | الأثر |
|---|---|---|---|
POST /v1/campaigns/:id/pause |
running |
paused |
لا يُؤخذ مستلم جديد. الرسائل التي استلمها هاتف تُرسل. |
POST /v1/campaigns/:id/resume |
paused |
running |
تبدأ السرعة من الآن دون دفعة مفاجئة. |
POST /v1/campaigns/:id/cancel |
scheduled أو running أو paused |
canceled |
نهائي. يُتخطى المستلمون المعلقون، وتُحظر الرسائل التي لم يستلمها هاتف مع errorCode: "campaign_canceled". |
أي انتقال آخر يعيد 409 invalid_campaign_state. لا يمكن تعديل (PATCH /v1/campaigns/:id) أو حذف إلا حملة بالحالة draft.
تصبح الحملة completed عندما لا يبقى مستلم معلق ولا تبقى من رسائلها رسالة queued أو routed أو sending.
متابعة التقدم
Section titled “متابعة التقدم”يتضمن GET /v1/campaigns/:id الحقل progress:
{ "recipients": 4812, "pending": 3020, "queued": 64, "sent": 1690, "delivered": 1544, "failed": 12, "skipped": 26, "ratePerMinute": 58, "etaAt": "2026-11-19T14:41:00.000Z"}اشترك في campaign.started وcampaign.completed لتتجنب الاستعلام المتكرر. كل رسالة في الحملة رسالة عادية تحمل metadata.campaignId، فتعمل webhooks message.* وGET /v1/messages?campaignId=cmp_… كالمعتاد.
عند انتهائها يعيد GET /v1/campaigns/:id/report أسباب التخطي ورموز الفشل والأعداد لكل هاتف ونسبة التسليم ومدى انحراف التنفيذ عن التقدير.
الاختبار في بيئة الاختبار
Section titled “الاختبار في بيئة الاختبار”ابدأ الحملة بمفتاح sf_test_ فتعمل في بيئة الاختبار: تُعلَّم الحملة sandbox: true، ويُعالج المستلمون بسرعة ratePerMinute، وتمر كل رسالة بالحالة sent ثم delivered دون هاتف. انظر بيئة الاختبار.