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

تشغيل حملة

ترسل الحملة رسالة واحدة إلى عدد كبير من جهات الاتصال. تأخذ SMSFabric لقطة من الجمهور، وتستبعد الأرقام الملغية للاشتراك والموجودة في القائمة السوداء، وتملأ متغيرات كل جهة اتصال، ثم تمرر الرسائل إلى هواتفك بالسرعة التي تحتملها. استخدمها بدل حلقة على POST /v1/messages كلما كان لديك أكثر من بضعة مستلمين.

تحتاج إلى:

  • جهات اتصال في مجموعات أو بوسوم. أنشئها عبر POST /v1/contacts أو استورد ملف CSV عبر POST /v1/contact-imports (انظر مرجع الاستيراد).
  • مفتاح بالصلاحيتين campaigns:manage وmessages:send (وcontacts:manage لإضافة جهات الاتصال).
  • هاتف متصل واحد على الأقل، إلا إذا كنت تختبر بمفتاح sf_test_.
  1. أنشئ مسودة عبر POST /v1/campaigns.
  2. افحصها عبر POST /v1/campaigns/:id/estimate: المستلمون والأجزاء والمدة والتحذيرات.
  3. ابدأها عبر POST /v1/campaigns/:id/start.
  4. تابع progress عبر GET /v1/campaigns/:id أو webhook campaign.completed، ثم اقرأ GET /v1/campaigns/:id/report.

أرسل 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 draft
curl 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. Estimate
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
# 3. Start
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

تُجمع groupIds (حتى 20) وtags (حتى 20): جهة الاتصال الموجودة في أي من المجموعات أو التي تحمل أيا من الوسوم تدخل الجمهور مرة واحدة. عند البدء تأخذ SMSFabric لقطة وتتخطى:

  • جهات الاتصال الملغية للاشتراك (ردت بكلمة STOP، أو عُلّمت optedOut)،
  • الأرقام الموجودة في القائمة السوداء،
  • الأرقام غير الصالحة، وجهات الاتصال التي تتجاوز رسالتها بعد ملء المتغيرات 1600 حرف.

البدء دون مستلمين يعيد 422 campaign_audience_empty. جهات الاتصال المضافة بعد البدء لا تُشمل.

الإعداد الافتراضي الأثر
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 بعض المستلمين في دول متعددة المناطق الزمنية.
الطلب من إلى الأثر
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.

يتضمن 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 دون هاتف. انظر بيئة الاختبار.