​

أرسل حملة من الطرف إلى الطرف

​

1. المتطلبات المسبقة

• مفتاح واجهة برمجية بنطاق campaigns:write. تقبل كل قراءة أدناه (معاينة الجمهور، الـ dry-run، الإحصاءات) أيضًا campaigns:read، لكن أفعال الإطلاق تتطلب write. أنشئ المفاتيح أو حررها في لوحة التحكم تحت Settings → API keys.
• Node SDK (اختياري). npm install @devotel-orbit/node إذا كنت تفضل تبويبات الـ SDK على cURL.
• هوية إرسال لقناتك. لـ SMS/MMS يعني ذلك رقمًا أو مجمع مرسلين بالتسجيلات الصحيحة (يتطلب A2P في الولايات المتحدة 10DLC)؛ ولـ WhatsApp حساب WABA متصلًا؛ ولبريد الإلكتروني نطاق إرسال موثقًا.
• مصدر جمهور معتمد. قائمة جهات اتصال، أو شريحة حية، أو CSV بعناوين المستلمين، أو جمهور CRM خارجي (قائمة HubSpot / تقرير Salesforce)، أو مجموعة معرفات جهات اتصال منتقاة يدويًا. يجب أن يأتي الجمهور من مستلمين مشتركين — فمعالجة الـ suppression وإلغاء الاشتراك تُفرض وقت الإرسال ولا تُترك للمرسل.

​

2. أنشئ حملة المسودة

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "fixed"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
});

​

3. اربط الجمهور وتحقق منه

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "channel": "sms"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// No typed helper wraps this endpoint — the SDK index
// ([/sdks](/sdks#node)) routes uncovered endpoints through
// the generic `request()` escape hatch.
const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

​

4. التخصيص واللغة

• تُحفظ الرموز حرفيًا عبر الترجمة.
• تبقى تعليمة opt-out الوحيدة مرة واحدة بالضبط (متطلب مشغلي الشبكات).

​

5. ما قبل الإطلاق: شغّل الـ dry-run

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const report = await orbit.request(
  "POST",
  `/campaigns/${"cmp_abc123"}/dry-run`,
);
// Same escape hatch as the audience preview above — no body needed.

• audience.total_in_audience — العدد الإجمالي للتطابقات.
• audience.suppressed / opted_out / unreachable — شرائح الإسقاط الصافي (قائمة الـ suppression، وحالات opt-out لكل قناة، وغياب عنوان القناة).
• audience.held_out — المستلمون المقتطعون في شريحة التحكم لقياس الزيادة عندما يكون variables.campaign_holdout_percent مضبوطًا؛ ويُستبعدون من التسليم.
• audience.deliverable — العدد الصافي الدقيق الذي سيحاول الإطلاق الوصول إليه.
• cost.unit_price_cents / cost.total_cents — تُسعَّر عبر المحلل نفسه الذي يستخدمه مسار الإرسال، فيتطابق الرقم مع خصم المحفظة ضمن حدود التقريب.
• cost.balance_cents / cost.sufficient — فحص المحفظة؛ الـ dry-run الأخضر يستلزم بوابة رصيد خضراء عند الإطلاق.
• quiet_hours.skipped_estimate وquiet_hours.window — نسبة التجاوز المتوقعة من ساعات الهدوء بتوقيت المستلم المحلي، إضافة إلى النافذة المحلولة قيد التقييم.
• channel_waterfall — القناة الأساسية وشكل التراجع بين القنوات، لتتحقق من RCS ← SMS (أو أي سلسلة ضبطتها) قبل الضغط على إرسال.
• warnings[] — مشكلات غير حاجبة (لا مزود مسجلًا للقناة، ساعات هدوء تغلق النافذة بالكامل …) تُعرض منفصلة عن الإخفاقات الصارمة.

• الموافقات. إذا كانت مؤسستك تتطلب توقيع مشرف، يعيد الإطلاق (POST /campaigns/:id/send) حالة انتظار موافقة بدل الإرسال؛ ويقع طابور الموافِقين عند GET /campaigns/approvals/pending، وإعدادات المؤسسة الافتراضية عند GET/PUT /campaigns/approvals/settings.
• جاهزية المزود. يفحص الـ dry-run نظافة القوائم وتسجيل المزود ضمنيًا عبر تحذيراته — قناة بلا مزود مهيأ تظهر هناك بدل أن تفشل وقت الإرسال.

​

6. أطلق واختر شكل الإرسال

• Throttle. يحد throttle_rate (رسائل/ثانية) من سرعة الإرسال — الافتراضي على المنصة 50 رسالة/ثانية؛ والقيمة 0 الصريحة تعني الافتراضي أيضًا.
• الإرسال الذكي. يجدول send_time_optimization: "recipient-optimal" كل مستلم في نافذة أفضل وقت له التالية من ملفات التفاعل، ويفرد التسليم على الساعات الأربع والعشرين التالية. عاينه أولًا بـPOST /campaigns/:id/preview-smart-send الذي يعيد أوقاتًا مقترحة لكل جهة اتصال إضافة إلى تلميح next_best_channel للعينة. ولقياس ما إذا كان التوقيت نفسه يؤتي ثماره، اشترك في شريحة hold-out لكل مستلم عبر variables.smart_send_holdout_pct — انظر الخطوة 7.
• معاينة القناة. إذا كانت قناة الحملة ما تزال مفتوحة، تحقق منها على عينة من المستلمين بـPOST /messages/route-preview — توصية الموجّه الذكي وسلسلة التراجع وكلفة كل رسالة ودرجة التفاعل، من دون إرسال شيء. لتسليح تلك السلسلة للإرسال (فيتدرج الفشل النهائي بدل التوقف عند أول قناة) مرّر cascade_policy في الطلب نفسه — يغطي دليل سلاسل تراجع الإرسال الذكي شكل السياسة لكل رسالة، ويمشي دليل معاينة المسار الذكي النقطة ونمط خط الإرسال.
• نافذة الإرسال. يؤجل send_window: { start_local_hour, end_local_hour } المستلمين الذين يقع وقتهم المحلي خارج النافذة — نافذة موجبة لكل مستلم، تختلف عن ساعات الهدوء (فلتر سالب).

​

7. راقب وقِس

​

8. اشترك في webhooks الحملة

• campaign.created / campaign.updated / campaign.deleted
• campaign.started / campaign.paused / campaign.resumed / campaign.cancelled / campaign.completed
• campaign.drip_step.sent / campaign.drip_step.completed / campaign.drip.completed

​

9. استكشاف الأخطاء وإصلاحها

• يحلّ الجمهور إلى صفر. أعد تشغيل معاينة الجمهور مع تمرير channel؛ يخبرك الإسقاط الصافي أي شريحة أفرغته (كله suppressed، أو كله opt-out، أو لا عنوان قابلًا للوصول). أصلح القائمة أو تغطية عناوين القناة، لا الحملة.
• يعرض الـ dry-run تحذيرات حمراء. إدخالات warnings[] صريحة — «no provider registered» تعني أن القناة بلا هوية إرسال مهيأة؛ و«quiet hours fully closed» تعني أن النافذة المحلولة ترفض كل ساعة محلية؛ و«insufficient balance» تعني cost.sufficient: false. أزل التحذير وأعد تشغيل الـ dry-run.
• يعيد الإطلاق 402 أو شكل انتظار موافقة. فشل فحص الرصيد، أو أن سير عمل الموافقات مفعّل — إمّا اشحن المحفظة أو انتظر POST /campaigns/approvals/:id/approve.
• حملة journey عالقة في paused. تتوقف الحملة تلقائيًا عند بلوغ credit_cap_usd_cents أو عند شرط drip معطوب. افحص GET /campaigns/:id/stats وأزل العائق ثم POST /campaigns/:id/resume. تحتفظ الـ journeys المتوقفة بحالة التسجيل؛ ويستأنف الاستمرار من حيث توقفت.
• يفرد الإرسال الذكي التسليم أكثر من اللازم. يوزع recipient-optimal الإرسالات عمدًا على 24 ساعة. إذا كنت تحتاج دفعة واحدة، اضبط send_time_optimization: "fixed" واستخدم send_window إذا امتد المستلمون عبر مناطق زمنية.

​

مثال عملي: promo تجزئة، من المسودة إلى التحليلات

1. أنشئ المسودة.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "recipient-optimal",
    "throttle_rate": 100,
    "variables": { "campaign_holdout_percent": 10 },
    "credit_cap_usd_cents": 50000
  }'

2. عاين الجمهور.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience_type": "list", "audience_id": "list_summerVIPs", "channel": "sms" }'

3. شغّل الـ dry-run.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

4. عاين أوقات الإرسال الذكي (اختياري).

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/preview-smart-send" \
  -H "X-API-Key: $ORBIT_API_KEY"

5. أطلق.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/send" \
  -H "X-API-Key: $ORBIT_API_KEY"

6. اشترك في أحداث دورة الحياة (campaign.started وcampaign.completed) واقرأ الإحصاءات مع تراكم حالات التسليم.
7. قِس. بعد اكتمال الإرسال:

curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/holdout-lift" \
  -H "X-API-Key: $ORBIT_API_KEY"
curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/roas" \
  -H "X-API-Key: $ORBIT_API_KEY"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
});
const id = campaign.data.id;

// Attach the audience plus the fields the typed helper doesn't carry
// (holdout percent, spend cap, throttle) via a partial update.
await orbit.request("PUT", `/campaigns/${id}`, {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  type: "blast",
  send_time_optimization: "recipient-optimal",
  throttle_rate: 100,
  variables: { campaign_holdout_percent: 10 },
  credit_cap_usd_cents: 50000,
});

const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

const dryRun = await orbit.request("POST", `/campaigns/${id}/dry-run`);

// Launch — the typed helper auto-generates an idempotency key.
await orbit.campaigns.send(id);

const lift = await orbit.request("GET", `/campaigns/${id}/holdout-lift`);
const roas = await orbit.request("GET", `/campaigns/${id}/roas`);