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

الحملات

ترسل الحملة رسالة واحدة إلى كل جهة اتصال في مجموعات أو بوسوم معينة، مرة واحدة لكل جهة اتصال، مع استبعاد الأرقام الملغية للاشتراك والموجودة في القائمة السوداء. انظر تشغيل حملة للشرح.

الحالات: draft ← scheduled ← running ⇄ paused ← completed، وcanceled من scheduled أو running أو paused. الحالتان completed وcanceled نهائيتان. أي انتقال آخر يعيد 409 invalid_campaign_state.

الحقل النوع الوصف
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
GET/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"
POST/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 مجموعة أو قالب أو مجموعة أجهزة أو هاتف أو شريحة لا تتبع مؤسستك.
GET/v1/campaigns/:idcampaigns:read
نافذة طرفيّة
curl https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

يعيد الحملة مع progress محدّث.

PATCH/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"}'
DELETE/v1/campaigns/:idcampaigns:manage

للمسودات فقط. يعيد 204.

نافذة طرفيّة
curl -X DELETE https://api.smsfabric.com/v1/campaigns/cmp_e1h4k7n0q3t6w9z2c5f8i1l4 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/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. انظر تشغيل حملة.

POST/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 الحملة ليست مسودة.
POST/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"
POST/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"
POST/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"
GET/v1/campaigns/:id/reportcampaigns:read
نافذة طرفيّة
curl 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 للرسائل.