الحملات
ترسل الحملة رسالة واحدة إلى كل جهة اتصال في مجموعات أو بوسوم معينة، مرة واحدة لكل جهة اتصال، مع استبعاد الأرقام الملغية للاشتراك والموجودة في القائمة السوداء. انظر تشغيل حملة للشرح.
الحالات: draft ← scheduled ← running ⇄ paused ← completed، وcanceled من scheduled أو running أو paused. الحالتان completed وcanceled نهائيتان. أي انتقال آخر يعيد 409 invalid_campaign_state.
كائن الحملة
Section titled “كائن الحملة”| الحقل | النوع | الوصف |
|---|---|---|
id |
string | cmp_… |
name |
string | |
status |
string | draft أو scheduled أو running أو paused أو completed أو canceled. |
templateId |
string أو null | القالب الذي أُخذ منه النص. |
body |
string | نسخة الحملة الخاصة من النص. |
variables |
string[] | المتغيرات في النص. |
audience |
object | { groupIds, tags }. |
route |
object | { poolId, deviceId, simId }. |
ratePerMinute |
integer | سقف السرعة. |
hourlyCap وdailyCap |
integer أو null | أقصى عدد من المستلمين في الساعة وفي اليوم حسب timeZone، وnull بلا حد. |
quietHours |
object أو null | { start, end } بصيغة HH:MM بالتوقيت المحلي للمستلمين. |
timeZone |
string | المنطقة الاحتياطية للأرقام مجهولة الدولة. |
sandbox |
boolean | true إذا بدأت بمفتاح sf_test_. |
scheduledAt وstartedAt وpausedAt وcompletedAt وcanceledAt |
string أو null | |
estimatedDurationMs |
integer أو null | التقدير عند البدء. |
segments |
integer | أجزاء النص بعد ملئه لجهة اتصال نموذجية. |
progress |
object | { recipients, pending, queued, sent, delivered, failed, skipped, ratePerMinute, etaAt, capped, cappedUntil }. تكون capped إما hourly أو daily ما دام الحد يوقف الحملة (وتبقى حالتها running)، وتذكر cappedUntil موعد فتح النافذة التالية. يشمل sent المسلّمة، ويُقاس ratePerMinute على آخر 30 ثانية. |
createdAt وupdatedAt |
string |
عرض الحملات
Section titled “عرض الحملات”/v1/campaignscampaigns:read| الاستعلام | النوع | الوصف |
|---|---|---|
status |
string | حالة حملة واحدة. |
limit |
integer | من 1 إلى 200، والافتراضي 50. |
cursor |
string | nextCursor من الصفحة السابقة. |
curl "https://api.smsfabric.com/v1/campaigns?status=running" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"إنشاء حملة
Section titled “إنشاء حملة”/v1/campaignscampaigns:manageينشئ حملة بالحالة draft ويعيد 201. يدعم Idempotency-Key.
| حقل المحتوى | النوع | إلزامي | الوصف | القيود |
|---|---|---|---|---|
name |
string | نعم | من 1 إلى 120 حرفا. | |
groupIds |
string[] | لا | مجموعات الجمهور. | حتى 20. |
tags |
string[] | لا | وسوم الجمهور. | حتى 20. |
templateId |
string | أحدهما | استخدم نص هذا القالب. | أرسل templateId أو body لا كليهما. |
body |
string | أحدهما | نص مباشر بالمتغيرات. | من 1 إلى 1600 حرف. |
poolId |
string | لا | وجّه عبر هذه المجموعة. | لا يجتمع مع deviceId/simId. |
deviceId وsimId |
string | لا | وجّه عبر هذا الهاتف أو هذه الشريحة. | يجب أن تكون الشريحة في الهاتف. |
ratePerMinute |
integer | لا | سقف السرعة. | من 1 إلى 6000، والافتراضي 120. |
hourlyCap |
integer أو null | لا | أقصى عدد من المستلمين في الساعة حسب timeZone. |
من 1 إلى 360000. |
dailyCap |
integer أو null | لا | أقصى عدد من المستلمين في اليوم حسب timeZone. |
من 1 إلى 8640000، ولا يقل عن hourlyCap. |
quietHours |
object أو null | لا | { "start": "21:00", "end": "09:00" }. |
HH:MM بنظام 24 ساعة، ويمكن أن تعبر منتصف الليل. |
timeZone |
string | لا | منطقة IANA احتياطية. | الافتراضي timeZone في تفضيلات مؤسستك. |
scheduledAt |
string | لا | وقت البدء الذي يستخدمه start. |
في المستقبل، حتى سنة مقدما. |
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"], "templateId": "tpl_h7k0n3q6t9w2z5c8f1i4l7o0", "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9", "ratePerMinute": 60, "quietHours": { "start": "21:00", "end": "09:00" } }'{ "id": "cmp_e1h4k7n0q3t6w9z2c5f8i1l4", "name": "Winter sale", "status": "draft", "templateId": "tpl_h7k0n3q6t9w2z5c8f1i4l7o0", "body": "Hi {{first_name|there}}, the winter sale starts Friday at {{custom.branch}}. Reply STOP to opt out.", "variables": ["first_name", "custom.branch"], "audience": { "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"], "tags": [] }, "route": { "poolId": "pool_c6f9j2m5p8s1v4y7b0e3h6k9", "deviceId": null, "simId": null }, "ratePerMinute": 60, "quietHours": { "start": "21:00", "end": "09:00" }, "timeZone": "Africa/Cairo", "sandbox": false, "scheduledAt": null, "startedAt": null, "pausedAt": null, "completedAt": null, "canceledAt": null, "estimatedDurationMs": null, "segments": 1, "progress": { "recipients": 0, "pending": 0, "queued": 0, "sent": 0, "delivered": 0, "failed": 0, "skipped": 0, "ratePerMinute": 0, "etaAt": null }, "createdAt": "2026-11-19T12:00:00.000Z", "updatedAt": "2026-11-19T12:00:00.000Z"}| الخطأ | متى |
|---|---|
400 validation_failed |
لا body ولا templateId أو كلاهما، أو poolId مع deviceId/simId، أو شريحة ليست في الهاتف، أو scheduledAt في الماضي. |
400 template_invalid |
في النص متغيرات غير صالحة. |
404 not_found |
مجموعة أو قالب أو مجموعة أجهزة أو هاتف أو شريحة لا تتبع مؤسستك. |
قراءة حملة
Section titled “قراءة حملة”/v1/campaigns/:idcampaigns:readcurl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"يعيد الحملة مع progress محدّث.
تحديث حملة
Section titled “تحديث حملة”/v1/campaigns/:idcampaigns:manageللمسودات فقط. يقبل أي حقل من حقول الإنشاء ويعيد الحملة، أو 409 invalid_campaign_state لأي حالة أخرى.
curl -X PATCH https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scheduledAt": "2026-11-21T08:00:00Z"}'حذف حملة
Section titled “حذف حملة”/v1/campaigns/:idcampaigns:manageللمسودات فقط. يعيد 204.
curl -X DELETE https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"تقدير حملة
Section titled “تقدير حملة”/v1/campaigns/:id/estimatecampaigns:readللمسودات والحملات المجدولة: المستلمون والأجزاء والمدة بحسب السقف وقدرة هواتفك وساعات الهدوء. يعيد 200. يُحتسب ضمن حد العمليات المجمعة.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/estimate \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "recipients": 4812, "excluded": { "blacklisted": 14, "optedOut": 37 }, "segments": 4890, "ucs2Recipients": 0, "devices": 3, "capacityPerMinute": 42, "effectiveRatePerMinute": 42, "waitingForQuietHours": 0, "multiZoneRecipients": 0, "unreachable": 0, "capDays": null, "durationMs": 6874000, "startsAt": "2026-11-19T12:05:00.000Z", "completesAt": "2026-11-19T13:59:34.000Z", "zones": [{ "zone": "Africa/Cairo", "recipients": 4812, "quietNow": false, "opensAt": null }], "warnings": ["capacity_below_throttle"]}segments هو مجموع الأجزاء لكل المستلمين، بعد ملء رسالة كل منهم بمتغيراته. التحذيرات: empty_audience وno_devices وcapacity_below_throttle وunreachable_recipients وmulti_zone_countries. انظر تشغيل حملة.
بدء حملة
Section titled “بدء حملة”/v1/campaigns/:id/startcampaigns:manage, messages:sendيأخذ لقطة الجمهور وينقل draft إلى running، أو إلى scheduled إذا كان scheduledAt في المستقبل. مع مفتاح sf_test_ تعمل الحملة في بيئة الاختبار. يعيد 200 مع الحملة. يُحتسب ضمن حد العمليات المجمعة. يُسجل في التدقيق باسم campaign.started ويرسل webhook campaign.started.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/start \ -H "X-Api-Key: $SMSFABRIC_API_KEY"| الخطأ | متى |
|---|---|
422 campaign_audience_empty |
لم تبق جهة اتصال بعد الاستبعاد. |
409 invalid_campaign_state |
الحملة ليست مسودة. |
إيقاف حملة مؤقتا
Section titled “إيقاف حملة مؤقتا”/v1/campaigns/:id/pausecampaigns:manageمن running إلى paused. لا يُؤخذ مستلم جديد، والرسائل التي استلمها هاتف تُرسل. يعيد الحملة. يُسجل في التدقيق باسم campaign.paused.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/pause \ -H "X-Api-Key: $SMSFABRIC_API_KEY"استئناف حملة
Section titled “استئناف حملة”/v1/campaigns/:id/resumecampaigns:manageمن paused إلى running. تبدأ السرعة من الآن دون دفعة مفاجئة. يعيد الحملة. يُسجل في التدقيق باسم campaign.resumed.
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/resume \ -H "X-Api-Key: $SMSFABRIC_API_KEY"إلغاء حملة
Section titled “إلغاء حملة”/v1/campaigns/:id/cancelcampaigns:manageمن scheduled أو running أو paused إلى canceled (نهائي). يُتخطى المستلمون المعلقون بالسبب canceled، وتُحظر الرسائل التي لم يستلمها هاتف مع errorCode: "campaign_canceled". يعيد الحملة. يُسجل في التدقيق باسم campaign.canceled ويرسل campaign.completed مع status: "canceled".
curl -X POST https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/cancel \ -H "X-Api-Key: $SMSFABRIC_API_KEY"تقرير الحملة
Section titled “تقرير الحملة”/v1/campaigns/:id/reportcampaigns:readcurl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4/report \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "campaign": { "id": "cmp_e1h4k7n0q3t6w9z2c5f8i1l4", "name": "Winter sale", "status": "completed" }, "skipped": { "blacklisted": 14, "opted_out": 37, "invalid_number": 3 }, "failures": { "no_service": 9, "generic_failure": 2 }, "byDevice": [ { "deviceId": "dev_m4p7s2v5y8b1e4h7k0n3q6t9", "deviceName": "Pixel 8 · front desk", "simId": "sim_r2t4v6x8z1b3d5f7h9j2l4n6", "queued": 0, "sent": 1598, "delivered": 1561, "failed": 5 } ], "durationMs": 7012000, "estimateDeviation": 0.02, "deliveryRate": 0.97}(اختُصر campaign هنا، وهو كائن الحملة كاملا.) أسباب التخطي: blacklisted وopted_out وcanceled وcontact_deleted وinvalid_number وbody_too_long (النص بعد ملئه لجهة الاتصال أطول من 1600 حرف). ويحسب failures قيم errorCode للرسائل.