تخطَّ إلى المحتوى
ساعيv1

الحملات

عرض بصيغة Markdown

أرسل قالبًا معتمدًا إلى جمهور وتابع النتائج.

ترسل الحملة قالبًا معتمدًا واحدًا إلى جهات اتصال كثيرة، بوتيرة تحمي رقمك، وتجمع لك نتائجها. استخدمها للإعلانات والعروض، أما الرسالة الواحدة التي يطلقها نظامك (تحديث طلب مثلًا) فأرسلها مباشرة عبر POST /messages.

كيف يعمل: الحملات1. أنشئ مسودة · 2. أجب عن سؤال الموافقة · 3. راجع التكلفة ثم ابدأ · 4. تابع النتائج · الإيقاف المؤقت والاستئناف والإلغاء

1. أنشئ مسودة#

يبني POST /campaigns قائمة المستلمين ويسعّرها، ولا يُرسل شيء بعد.

JSON
{
  "name": "عرض نهاية الأسبوع",
  "template": { "name": "weekend_offer", "language": "ar" },
  "audience": { "tags": ["عملاء VIP"] },
  "variables": { "body": ["{{first_name}}", "20٪"] },
  "scheduled_at": "2026-10-02T16:00:00",
  "timezone": "Asia/Riyadh"
}
  • الجمهور. contacts (معرّفات)، أو tags (معرّفات أو أسماء)، أو "all_contacts": true.
  • القيم الشخصية. في variables تُعبَّأ {{first_name}} و{{last_name}} و{{phone_number}} أو أي مفتاح حقل مخصص لكل مستلم.
  • الجدولة. scheduled_at وقت محلي يُقرأ حسب timezone. اتركه لتُرسل فور البدء.
  • الأرقام. إن كان لديك أكثر من رقم واتساب فحدد رقم الإرسال بـ number_id، ويجب أن يعود القالب لحساب هذا الرقم.

2. أجب عن سؤال الموافقة#

إن كان بعض المستلمين قد ألغوا اشتراكهم في رسائل الأعمال فالرد هو recipient_not_consented مع الأعداد:

JSON
{ "error": { "code": "recipient_not_consented", "unconsented": 12, "recipients": 348, "param": "consent_confirmed", "...": "..." } }

أعد الطلب مع "consent_confirmed": false لاستبعادهم، أو true فقط إن وافقوا من جديد. تُسجَّل إجابتك في سجل التدقيق.

3. راجع التكلفة ثم ابدأ#

تحمل المسودة estimated_cost: ما سيحتسبه واتساب بالريال بأسعار اليوم، مع عدد المستلمين المسعّرين والمجانيين وغير المسعّرين. حين تبدو مناسبة استدعِ POST /campaigns/{id}/start.

يُجري البدء الفحوص نفسها التي تجريها المنصة: يجب أن يستطيع الرقم البث (الرقم الذي قيّده Meta لا يستطيع)، وألا يوقف Meta التسليم لسبب يتعلق بالفوترة، وأن يغطي رصيد الباقة الشهري من الحملات والرسائل التسويقية الإرسال (وإلا فالخطأ quota_exceeded).

4. تابع النتائج#

  • يعطي GET /campaigns/{id} الإحصاءات stats لحظيًا: المرسلة والمسلّمة والمقروءة والفاشلة والتي رُدّ عليها والنسب.
  • يعرض GET /campaigns/{id}/messages رسالة كل مستلم مع حالتها، وسبب واتساب عند الفشل.
  • الأحداث: campaign.started وcampaign.completed، وmessage.* لكل مستلم (تبدأ المعرّفات بـ cmsg_).

الإيقاف المؤقت والاستئناف والإلغاء#

يتم الإرسال بوتيرة محسوبة. إن اصطدم الرقم بحد وضعه Meta تُوقف الحملة مؤقتًا (status: paused، ويوضح hold_reason السبب) ويصلك campaign.paused. أصلح السبب ثم استدعِ POST /campaigns/{id}/resume: لا تُستأنف الحملة المتوقفة من تلقاء نفسها، لأن الرقم العائد من قيد يجب ألا يبدأ البث دون متابعة.

يوقف POST /campaigns/{id}/cancel حملة مجدولة أو قيد الإرسال، وتبقى الرسائل المرسلة كما هي.

نقاط الواجهة

عرض الحملات

gethttps://api.saei.automize.sa/v1/campaigns
  • الصلاحية: campaigns:read
  • لمفاتيح التشغيل فقط

معاملات الاستعلام

  • limitintegerاختياري

    عدد العناصر المطلوبة، من 1 إلى 100.

  • cursorstringاختياري

    قيمة next_cursor من الصفحة السابقة.

  • statusstringاختياري

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

حقول الاستجابة200
  • object"list"مطلوب
  • dataarray<Campaign>مطلوب
    الحقول الفرعية (14)
    • idstringمطلوب
    • object"campaign"مطلوب
    • namestringمطلوب
    • descriptionstring | nullاختياري
    • statusstringمطلوب

      draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

      إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

    • hold_reasonstring | nullاختياري
    • templateobject | nullاختياري
      الحقول الفرعية (3)
      • idstringاختياري
      • namestringاختياري
      • languagestring | nullاختياري
    • number_idstring | nullاختياري
    • scheduled_atstring | nullاختياري
    • timezonestring | nullاختياري
    • statsobjectمطلوب

      أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

      الحقول الفرعية (10)
      • recipientsintegerاختياري
      • pendingintegerاختياري
      • sentintegerاختياري
      • deliveredintegerاختياري
      • readintegerاختياري
      • failedintegerاختياري
      • repliedintegerاختياري
      • delivery_ratenumber | nullاختياري
      • read_ratenumber | nullاختياري
      • reply_ratenumber | nullاختياري
    • estimated_costobject | nullاختياري

      ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

      الحقول الفرعية (6)
      • currencystringاختياري
      • totalnumberاختياري
      • total_usdnumberاختياري
      • recipients_pricedintegerاختياري
      • recipients_freeintegerاختياري
      • recipients_unpricedintegerاختياري
    • created_atstring | nullاختياري
    • updated_atstring | nullاختياري
  • has_morebooleanمطلوب
  • next_cursorstring | nullمطلوب
الأخطاء المحتملة3
جرّبها
curl -X GET https://api.saei.automize.sa/v1/campaigns \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

صفحة من الحملات.

{
  "object": "list",
  "data": [
    {
      "id": "cmp_64",
      "object": "campaign",
      "name": "string",
      "description": "string",
      "status": "draft",
      "hold_reason": "string",
      "template": {
        "id": "string",
        "name": "string",
        "language": "string"
      },
      "number_id": "string",
      "scheduled_at": "2026-10-01T09:30:00Z",
      "timezone": "string",
      "stats": {
        "recipients": 0,
        "pending": 0,
        "sent": 0,
        "delivered": 0,
        "read": 0,
        "failed": 0,
        "replied": 0,
        "delivery_rate": 0,
        "read_rate": 0,
        "reply_rate": 0
      },
      "estimated_cost": {
        "currency": "string",
        "total": 0,
        "total_usd": 0,
        "recipients_priced": 0,
        "recipients_free": 0,
        "recipients_unpriced": 0
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

إنشاء حملة

posthttps://api.saei.automize.sa/v1/campaigns
  • الصلاحية: campaigns:write
  • لمفاتيح التشغيل فقط
  • يقبل Idempotency-Key

ينشئ مسودة: لا يُرسل شيء حتى تستدعي POST /v1/campaigns/{id}/start. يحمل الرد estimated_cost، أي التكلفة التي سيحتسبها واتساب بأسعار اليوم، لتؤكد قبل الإرسال.

  • الجمهور: contacts (معرّفات)، أو tags (معرّفات أو أسماء)، أو all_contacts: true.
  • المتغيرات: قيم القالب، حيث تُعبَّأ {{first_name}} و{{last_name}} و{{phone_number}} أو أي مفتاح حقل مخصص لكل مستلم، مثل "body": ["{{first_name}}", "20%"].
  • الموافقة: إن كان بعض المستلمين قد ألغوا اشتراكهم في رسائل الأعمال فالرد هو recipient_not_consented مع الأعداد. أرسل consent_confirmed: false لتخطيهم، أو true فقط إن وافقوا من جديد (يُسجَّل تأكيدك في سجل التدقيق).

كل فحوص منشئ الحملات تنطبق هنا أيضًا: الرقم الذي قيّده Meta لا يستطيع البث، ويجب أن يعود القالب لرقم الإرسال، وتُطبق حدود الباقة الشهرية للحملات والرسائل التسويقية عند البدء.

الترويسات

  • Idempotency-Keystringاختياري

    أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

  • namestringمطلوب
  • descriptionstringاختياري
  • templateobjectمطلوب

    {"id": "tpl_…"} أو {"name": …, "language": …}. يجب أن يكون معتمدًا.

    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestringاختياري
  • number_idstringاختياري

    رقم الإرسال. مطلوب إن كان لدى مساحة العمل أكثر من رقم.

  • audienceobjectمطلوب
    الحقول الفرعية (3)
    • contactsarray<string>اختياري
    • tagsarray<string>اختياري
    • all_contactsbooleanاختياري
  • variablesobjectاختياري

    متغيرات القالب (كما في POST /v1/messages) مع متغيرات لكل مستلم مثل {{first_name}}.

  • scheduled_atstringاختياري

    تاريخ ووقت محلي في المستقبل يُقرأ بحسب timezone. اتركه لتُرسل عند البدء.

  • timezonestringاختياري
  • link_trackingbooleanاختياري

    احتساب النقرات على أزرار الروابط في القالب.

  • consent_confirmedbooleanاختياري
حقول الاستجابة201
  • idstringمطلوب
  • object"campaign"مطلوب
  • namestringمطلوب
  • descriptionstring | nullاختياري
  • statusstringمطلوب

    draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

  • hold_reasonstring | nullاختياري
  • templateobject | nullاختياري
    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestring | nullاختياري
  • number_idstring | nullاختياري
  • scheduled_atstring | nullاختياري
  • timezonestring | nullاختياري
  • statsobjectمطلوب

    أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

    الحقول الفرعية (10)
    • recipientsintegerاختياري
    • pendingintegerاختياري
    • sentintegerاختياري
    • deliveredintegerاختياري
    • readintegerاختياري
    • failedintegerاختياري
    • repliedintegerاختياري
    • delivery_ratenumber | nullاختياري
    • read_ratenumber | nullاختياري
    • reply_ratenumber | nullاختياري
  • estimated_costobject | nullاختياري

    ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

    الحقول الفرعية (6)
    • currencystringاختياري
    • totalnumberاختياري
    • total_usdnumberاختياري
    • recipients_pricedintegerاختياري
    • recipients_freeintegerاختياري
    • recipients_unpricedintegerاختياري
  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة10
جرّبها
curl -X POST https://api.saei.automize.sa/v1/campaigns \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "عرض نهاية الأسبوع",
  "template": {
    "name": "weekend_offer",
    "language": "ar"
  },
  "number_id": "num_3",
  "audience": {
    "tags": [
      "عملاء VIP"
    ]
  },
  "variables": {
    "body": [
      "20٪"
    ]
  },
  "scheduled_at": "2026-10-02T16:00:00",
  "timezone": "Asia/Riyadh"
}'
الاستجابة

المسودة مع تقدير تكلفتها.

{
  "id": "cmp_64",
  "object": "campaign",
  "name": "عرض نهاية الأسبوع",
  "description": null,
  "status": "draft",
  "hold_reason": null,
  "template": {
    "id": "tpl_31",
    "name": "weekend_offer",
    "language": "ar"
  },
  "number_id": "num_3",
  "scheduled_at": "2026-10-02T13:00:00Z",
  "timezone": "Asia/Riyadh",
  "stats": {
    "recipients": 348,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0
  },
  "estimated_cost": {
    "currency": "SAR",
    "total": 61.25,
    "total_usd": 16.33,
    "recipients_priced": 348,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T10:00:00Z",
  "updated_at": "2026-10-01T10:00:00Z"
}

جلب حملة

gethttps://api.saei.automize.sa/v1/campaigns/{id}
  • الصلاحية: campaigns:read
  • لمفاتيح التشغيل فقط

الحملة مع نتائجها لحظيًا (أُرسلت، سُلّمت، قُرئت، فشلت، رُدّ عليها، والنسب).

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • object"campaign"مطلوب
  • namestringمطلوب
  • descriptionstring | nullاختياري
  • statusstringمطلوب

    draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

  • hold_reasonstring | nullاختياري
  • templateobject | nullاختياري
    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestring | nullاختياري
  • number_idstring | nullاختياري
  • scheduled_atstring | nullاختياري
  • timezonestring | nullاختياري
  • statsobjectمطلوب

    أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

    الحقول الفرعية (10)
    • recipientsintegerاختياري
    • pendingintegerاختياري
    • sentintegerاختياري
    • deliveredintegerاختياري
    • readintegerاختياري
    • failedintegerاختياري
    • repliedintegerاختياري
    • delivery_ratenumber | nullاختياري
    • read_ratenumber | nullاختياري
    • reply_ratenumber | nullاختياري
  • estimated_costobject | nullاختياري

    ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

    الحقول الفرعية (6)
    • currencystringاختياري
    • totalnumberاختياري
    • total_usdnumberاختياري
    • recipients_pricedintegerاختياري
    • recipients_freeintegerاختياري
    • recipients_unpricedintegerاختياري
  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة3
جرّبها
curl -X GET https://api.saei.automize.sa/v1/campaigns/cmp_64 \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

الحملة.

{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

إلغاء حملة

posthttps://api.saei.automize.sa/v1/campaigns/{id}/cancel
  • الصلاحية: campaigns:write
  • لمفاتيح التشغيل فقط

يوقف حملة مجدولة أو قيد الإرسال. تبقى الرسائل المرسلة كما هي، وتُلغى البقية.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • object"campaign"مطلوب
  • namestringمطلوب
  • descriptionstring | nullاختياري
  • statusstringمطلوب

    draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

  • hold_reasonstring | nullاختياري
  • templateobject | nullاختياري
    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestring | nullاختياري
  • number_idstring | nullاختياري
  • scheduled_atstring | nullاختياري
  • timezonestring | nullاختياري
  • statsobjectمطلوب

    أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

    الحقول الفرعية (10)
    • recipientsintegerاختياري
    • pendingintegerاختياري
    • sentintegerاختياري
    • deliveredintegerاختياري
    • readintegerاختياري
    • failedintegerاختياري
    • repliedintegerاختياري
    • delivery_ratenumber | nullاختياري
    • read_ratenumber | nullاختياري
    • reply_ratenumber | nullاختياري
  • estimated_costobject | nullاختياري

    ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

    الحقول الفرعية (6)
    • currencystringاختياري
    • totalnumberاختياري
    • total_usdnumberاختياري
    • recipients_pricedintegerاختياري
    • recipients_freeintegerاختياري
    • recipients_unpricedintegerاختياري
  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة4
جرّبها
curl -X POST https://api.saei.automize.sa/v1/campaigns/cmp_64/cancel \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

أُلغيت.

{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

عرض مستلمي حملة

gethttps://api.saei.automize.sa/v1/campaigns/{id}/messages
  • الصلاحية: campaigns:read
  • لمفاتيح التشغيل فقط

رسالة message لكل مستلم (cmsg_…) مع حالة التسليم، وسبب واتساب عند الفشل. تصلك تغيّرات حالتها أيضًا كأحداث message.*.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

معاملات الاستعلام

  • limitintegerاختياري

    عدد العناصر المطلوبة، من 1 إلى 100.

  • cursorstringاختياري

    قيمة next_cursor من الصفحة السابقة.

  • statusstringاختياري

    إحدى القيمpendingsentdeliveredreadfailedcancelled

حقول الاستجابة200
  • object"list"مطلوب
  • dataarray<Message>مطلوب
    الحقول الفرعية (28)
    • idstringمطلوب

      معرّف فريد. عامله كنص معتم وخزّنه كنص حتى 64 حرفًا.

    • object"message"مطلوب
    • livemodebooleanمطلوب
    • directionstringمطلوب

      outbound للرسائل التي ترسلها، وinbound لرسائل العملاء.

      إحدى القيمoutboundinbound

    • channelstringمطلوب

      إحدى القيمwhatsappinstagrammessenger

    • fromstring | nullاختياري

      المُرسِل، بصيغة E.164 في واتساب.

    • tostring | nullاختياري

      المُستلِم، بصيغة E.164 في واتساب.

    • typestringمطلوب

      نوع محتوى الرسالة.

    • textobjectاختياري
      الحقول الفرعية (1)
      • bodystringاختياري
    • templateobjectاختياري
      الحقول الفرعية (4)
      • namestringاختياري
      • languagestringاختياري
      • variablesobjectاختياري
      • bodystringاختياري
    • imageobjectاختياري

      رسائل الوسائط تحمل link (أو media_id) وcaption وfilename وmime_type عند توفرها.

    • videoobjectاختياري
    • audioobjectاختياري
    • documentobjectاختياري
    • stickerobjectاختياري
    • locationobjectاختياري
    • contactsarrayاختياري
    • interactiveobjectاختياري

      ما أرسلته (type وbody وbuttons…)، أو عند ضغط العميل: reply: {id, title}.

    • reactionobjectاختياري
    • statusstringمطلوب

      accepted ← sent ← delivered ← read، أو failed. رسائل العملاء حالتها received. تصلك تغيّرات الحالة كأحداث ويب هوك.

      إحدى القيمacceptedsentdeliveredreadfailedreceived

    • errorobject | nullاختياري

      سبب فشل التسليم، عندما تكون status هي failed.

      الحقول الفرعية (3)
      • codestring | nullاختياري
      • titlestring | nullاختياري
      • messagestring | nullاختياري
    • referencestring | nullاختياري

      مرجعك الخاص، يُعاد كما أرسلته في طلب الإرسال وفي كل حدث.

    • conversation_idstring | nullاختياري
    • provider_message_idstring | nullاختياري

      معرّف الرسالة لدى واتساب (wamid).

    • contactobject | nullاختياري
      الحقول الفرعية (1)
      • namestring | nullاختياري
    • contextobject | nullاختياري

      في الرد، الرسالة التي يُرَد عليها.

      الحقول الفرعية (1)
      • provider_message_idstringاختياري
    • created_atstring | nullمطلوب
    • updated_atstring | nullاختياري
  • has_morebooleanمطلوب
  • next_cursorstring | nullمطلوب
الأخطاء المحتملة4
جرّبها
curl -X GET https://api.saei.automize.sa/v1/campaigns/cmp_64/messages \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

صفحة من رسائل المستلمين.

{
  "object": "list",
  "data": [
    {
      "id": "msg_48213",
      "object": "message",
      "livemode": false,
      "direction": "outbound",
      "channel": "whatsapp",
      "from": "+966112345678",
      "to": "+966501234567",
      "type": "text",
      "text": {
        "body": "string"
      },
      "template": {
        "name": "string",
        "language": "string",
        "variables": {},
        "body": "string"
      },
      "image": {},
      "video": {},
      "audio": {},
      "document": {},
      "sticker": {},
      "location": {},
      "contacts": [],
      "interactive": {},
      "reaction": {},
      "status": "accepted",
      "error": {
        "code": "string",
        "title": "string",
        "message": "string"
      },
      "reference": "string",
      "conversation_id": "string",
      "provider_message_id": "string",
      "contact": {
        "name": "string"
      },
      "context": {
        "provider_message_id": "string"
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

استئناف حملة متوقفة

posthttps://api.saei.automize.sa/v1/campaigns/{id}/resume
  • الصلاحية: campaigns:write
  • لمفاتيح التشغيل فقط

يعيد حملة متوقفة إلى الإرسال بعد إصلاح السبب. لا يحدث إلا بطلب صريح وليس تلقائيًا (إلا بعد إيقاف شامل للمنصة)، لأن الرقم العائد من قيد يجب ألا يبدأ البث دون متابعة. يُرفض ما دام الرقم لا يستطيع البث.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • object"campaign"مطلوب
  • namestringمطلوب
  • descriptionstring | nullاختياري
  • statusstringمطلوب

    draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

  • hold_reasonstring | nullاختياري
  • templateobject | nullاختياري
    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestring | nullاختياري
  • number_idstring | nullاختياري
  • scheduled_atstring | nullاختياري
  • timezonestring | nullاختياري
  • statsobjectمطلوب

    أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

    الحقول الفرعية (10)
    • recipientsintegerاختياري
    • pendingintegerاختياري
    • sentintegerاختياري
    • deliveredintegerاختياري
    • readintegerاختياري
    • failedintegerاختياري
    • repliedintegerاختياري
    • delivery_ratenumber | nullاختياري
    • read_ratenumber | nullاختياري
    • reply_ratenumber | nullاختياري
  • estimated_costobject | nullاختياري

    ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

    الحقول الفرعية (6)
    • currencystringاختياري
    • totalnumberاختياري
    • total_usdnumberاختياري
    • recipients_pricedintegerاختياري
    • recipients_freeintegerاختياري
    • recipients_unpricedintegerاختياري
  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة5
جرّبها
curl -X POST https://api.saei.automize.sa/v1/campaigns/cmp_64/resume \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

عادت للإرسال.

{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

بدء حملة

posthttps://api.saei.automize.sa/v1/campaigns/{id}/start
  • الصلاحية: campaigns:write
  • لمفاتيح التشغيل فقط

يرسل المسودة الآن، أو في موعد scheduled_at. يتم الإرسال بوتيرة تحمي تقييم جودة الرقم، وتابع التقدم بأحداث campaign.* وGET /v1/campaigns/{id}.

معاملات المسار

  • idstringمطلوب

    معرّف العنصر.

حقول الاستجابة200
  • idstringمطلوب
  • object"campaign"مطلوب
  • namestringمطلوب
  • descriptionstring | nullاختياري
  • statusstringمطلوب

    draft حتى تبدأ، وscheduled تنتظر scheduled_at، وpaused متوقفة مؤقتًا (انظر hold_reason): أصلح السبب ثم استدعِ POST /v1/campaigns/{id}/resume.

    إحدى القيمdraftscheduledin_progresspausedcompletedfailedcancelled

  • hold_reasonstring | nullاختياري
  • templateobject | nullاختياري
    الحقول الفرعية (3)
    • idstringاختياري
    • namestringاختياري
    • languagestring | nullاختياري
  • number_idstring | nullاختياري
  • scheduled_atstring | nullاختياري
  • timezonestring | nullاختياري
  • statsobjectمطلوب

    أعداد المستلمين. يضيف GET /v1/campaigns/{id} الحقول pending وreplied والنسب.

    الحقول الفرعية (10)
    • recipientsintegerاختياري
    • pendingintegerاختياري
    • sentintegerاختياري
    • deliveredintegerاختياري
    • readintegerاختياري
    • failedintegerاختياري
    • repliedintegerاختياري
    • delivery_ratenumber | nullاختياري
    • read_ratenumber | nullاختياري
    • reply_ratenumber | nullاختياري
  • estimated_costobject | nullاختياري

    ما سيحتسبه واتساب بالريال (والدولار) وفق جدول الأسعار الحالي. يُثبَّت عند البدء، وهو تقدير في المسودة.

    الحقول الفرعية (6)
    • currencystringاختياري
    • totalnumberاختياري
    • total_usdnumberاختياري
    • recipients_pricedintegerاختياري
    • recipients_freeintegerاختياري
    • recipients_unpricedintegerاختياري
  • created_atstring | nullاختياري
  • updated_atstring | nullاختياري
الأخطاء المحتملة8
جرّبها
curl -X POST https://api.saei.automize.sa/v1/campaigns/cmp_64/start \
  -H "Authorization: Bearer $API_KEY"
الاستجابة

بدأت (`in_progress`) أو جُدولت (`scheduled`).

{
  "id": "cmp_64",
  "object": "campaign",
  "name": "string",
  "description": "string",
  "status": "draft",
  "hold_reason": "string",
  "template": {
    "id": "string",
    "name": "string",
    "language": "string"
  },
  "number_id": "string",
  "scheduled_at": "2026-10-01T09:30:00Z",
  "timezone": "string",
  "stats": {
    "recipients": 0,
    "pending": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "replied": 0,
    "delivery_rate": 0,
    "read_rate": 0,
    "reply_rate": 0
  },
  "estimated_cost": {
    "currency": "string",
    "total": 0,
    "total_usd": 0,
    "recipients_priced": 0,
    "recipients_free": 0,
    "recipients_unpriced": 0
  },
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}