واجهة برمجة تطبيقات البث (Broadcasts API) #

يُعد البث عملية إرسال واحدة للخارج: جمهور، ورسالة افتتاحية، وقناة واحدة، وجدول زمني. ويمكنه اختياريًا تحديد وكيل الذكاء الاصطناعي (AI Agent) الذي يتولى الردود الواردة. تتيح لك واجهة برمجة تطبيقات البث إنشاء هذه الرسائل وتسعيرها وإطلاقها ومراقبتها من خلال الكود الخاص بك بدلاً من لوحة التحكم. للمنتج نفسه، راجع دليل البث.

• عنوان URL الأساسي — https://api.youraiconnector.com/v1
• المصادقة — مفتاح واجهة برمجة التطبيقات الخاص بك (راجع المصادقة)
• الأخطاء والترقيم — راجع الأخطاء والترقيم

توضح جميع الأمثلة أدناه نموذج الاستعلام ?apiKey= في cURL ورأس X-API-Key في JavaScript وPython — كلاهما يعمل على كل نقطة نهاية.

في مستكشف واجهة برمجة التطبيقات. كل نقطة نهاية في هذه الصفحة موجودة في مواصفات OpenAPI المنشورة، لذا يمكنك تصفح حقولها بدقة وتشغيل طلبات مباشرة في مستكشف واجهة برمجة التطبيقات.

كيف يتم تجميع عملية الإرسال #

إرسال بث يتطلب أربع استدعاءات، وليس واحدة:

1. إنشاء البث مع جمهوره وقناته وجدوله الزمني — يبدأ كـ Draft.
2. تعيين الرسالة الافتتاحية. في WhatsApp Business، يعني هذا إرسال قالب للموافقة عليه (أو اختيار قالب تمت الموافقة عليه مسبقًا). في أي قناة أخرى، يكون النص عاديًا.
3. تقدير التكلفة إذا كنت ترغب في التحقق من السعر قبل إنفاق أي شيء (اختياري).
4. إطلاقه. يقوم الإطلاق بإجراء فحص كامل — الجمهور، الرسالة، الموافقة على القالب، المرسل المتصل — ثم يبدأ الإرسال أو يخبرك بالضبط بما هو مفقود.

لا يتم إرسال أي شيء حتى تقوم باستدعاء الإطلاق.

كائن البث #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

تأتي الطوابع الزمنية كملي ثانية من الحقبة (epoch milliseconds) (execution_date، created_at، last_modified_at، …)، ويأتي أي مرجع لجهة اتصال كسلسلة مسار مثل contacts/uid_whatsapp_15551234567.

الحقول التي تقوم بتعيينها #

أي شيء ترسله كـ user_id أو id أو status أو source_campaign_id يتم تجاهله عند الإنشاء وإسقاطه عند التحديث — الحالة تنتقل فقط عبر نقاط نهاية الإطلاق والإيقاف المؤقت والاستئناف أدناه.

الحقول التي تحتفظ بها المنصة #

status، total_contacts_sent، unique_contacts_replied، overall_reply_rate، credits_used، paused_reason، completion_summary، عدادات الدفعات، و contacts (جهات الاتصال الفردية المرفقة من لوحة التحكم، مقروءة كسلاسل مسار). اقرأها، ولا تكتبها.

الحالات #

إنشاء بث #

POST /broadcasts — ينشئ Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

الاستجابة (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

سرد عمليات البث #

GET /broadcasts — كل بث على الحساب، الأحدث أولاً.

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

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

الاستجابة (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

الحصول على بث #

GET /broadcasts/{broadcastId} — يُرجع { "success": true, "broadcast": { ... } }. استخدمه لاستطلاع حالة إرسال قيد التشغيل: total_contacts_sent، وunique_contacts_replied، وoverall_reply_rate، وcredits_used يتم تحديثها أثناء العملية.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

البث غير الموجود في حسابك يُرجع 404.

تحديث بث #

PUT /broadcasts/{broadcastId} — أرسل فقط الحقول التي تريد تغييرها. يمكنك أيضاً معالجة مفتاح واحد داخل كائن متداخل باستخدام مسار منقط، على سبيل المثال "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

الجسم الفارغ يُرجع 400. قاعدتان تجدر معرفتهما:

• opener_media هو إما الكل أو لا شيء. أرسل الكائن كاملاً، أو null لإزالة المرفق. المسار المنقط إليه (opener_media.name) يتم رفضه بـ 400، لأن المرفق الذي تم تحديثه جزئياً سيصف ملفاً غير موجود.
• الحالة غير قابلة للتعديل. استخدم الإطلاق، والإيقاف المؤقت، والاستئناف.

رسالة الافتتاح #

يحمل كل بث رسالته الافتتاحية في whats_app_template. يعتمد معنى ذلك على القناة:

• WhatsApp Business — يجب أن تكون قالباً معتمداً من واتساب. استخدم إحدى نقطتي النهاية أدناه.
• أي قناة أخرى (WhatsApp Web، الرسائل القصيرة SMS، إنستغرام، ماسنجر، تيليجرام، …) — يكون body الخاص بنفس الحقل هو ببساطة النص الذي يتم إرساله. يؤدي إرساله عبر نقطة النهاية أدناه إلى تخزينه ووضع علامة “جاهز” عليه دون تدخل من واتساب على الإطلاق.

إرسال قالب للموافقة #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

الاستجابة (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status هو ما يقوله واتساب: pending أثناء مراجعته، وapproved عندما يصبح قابلاً للاستخدام، وrejected إذا تم رفضه. في القنوات غير التابعة لواتساب، يتم الرد مباشرة بـ approved مع template_sid: null — لا يوجد شيء للمراجعة.

الأمور التي قد تعيقك:

• الإرسال أثناء وجود قالب سابق قيد المراجعة يُرجع 400. انتظر القرار أولاً.
• تعديل قالب معتمد حالياً يبقي القالب المعتمد فعالاً حتى عودة القالب الجديد، بحيث لا يفقد البث الجاري رسالته الافتتاحية أبداً.
• على رقم واتساب متصل مباشرة عبر Meta، لا يمكن إرسال بث مرفق بصورة أو فيديو (400) — المرفقات مدعومة في مسار WhatsApp Business المُدار وعلى WhatsApp Web.

استخدام قالب تمت الموافقة عليه مسبقاً #

POST /broadcasts/{broadcastId}/template/select — ينسخ قالباً معتمداً مسبقاً من مكتبة القوالب الخاصة بك إلى البث، لذا لا يوجد شيء لانتظاره.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

الاستجابة (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

يتم التحقق من الموافقة من جانبنا بناءً على سجل المكتبة — أنت ترسل المعرف فقط. ستحصل على 400 إذا لم يكن البث مسودة واتساب، أو إذا لم يكن القالب معتمداً، أو إذا كان قالب متابعة بدلاً من كونه افتتاحياً، أو إذا كان البث يحتوي على مرفق (قوالب المكتبة نصية فقط). معرف القالب غير الموجود في حسابك يُرجع 404.

تقدير التكلفة #

POST /broadcasts/{broadcastId}/estimate-cost — يحدد سعر الإرسال قبل الالتزام به. متاح في بثوث whatsapp وsms؛ أي قناة أخرى تُرجع 400. يحتاج البث إلى list_id، لأن التقدير يعتمد على عدد الجمهور.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

استجابة واتساب (200) — الأرصدة، مقسمة حسب بلد الوجهة:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

استجابة الرسائل القصيرة (SMS) (200) — بالدولار الأمريكي، بناءً على أسعار Twilio المباشرة لحساب Twilio الخاص بك:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

اقرأ billing_mode قبل عرض الرقم. يوضح لك من الذي يتم محاسبته:

الرسائل القصيرة بدون بيانات اعتماد Twilio متصلة لا تزال تعيد أعداد الأجزاء، مع estimatedCostUsd: 0 — لا توجد أسعار للبحث عنها.

إطلاق بث #

POST /broadcasts/{broadcastId}/launch

يقوم الإطلاق بالتحقق من كل شيء أولاً ثم ينتقل بالبث إلى الأمام. لا يوجد إطلاق جزئي: إما أن يبدأ، أو لا يتغير شيء وتحصل على خطأ يوضح السبب.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

الاستجابة (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status هو المكان الذي وصل إليه البث:

• Scheduled — execution_date في المستقبل.
• Sending — بدأ الآن.
• Pending Approval — قالب WhatsApp لا يزال قيد المراجعة. سيتم إرساله بمجرد الموافقة على القالب؛ لا تطلب الإطلاق مرة أخرى.

فقط Draft (أو بث Pending Approval تمت الموافقة على قالبه منذ ذلك الحين) يمكن إطلاقه — أي شيء آخر يعيد 400.

لماذا يتم رفض الإطلاق #

كل واحدة من هذه تعود كـ 400 مع رسالة error بلغة واضحة:

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

POST /broadcasts/{broadcastId}/pause يوقف بث Sending أو Scheduled مؤقتاً ويزيل أي شيء موجود في قائمة الانتظار.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

يؤدي إيقاف بث Pending Approval مؤقتاً إلى إعادته إلى Draft بدلاً من ذلك — لم يتم جدولة أي شيء بعد، لذا لا يوجد شيء يمكن استئنافه. أي حالة أخرى تعيد 400.

POST /broadcasts/{broadcastId}/resume يعيد تشغيل بث Paused:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

الاستجابة (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

يتم استئنافه في Sending، أو العودة إلى Scheduled إذا كان execution_date الخاص به لا يزال في المستقبل. يمكن فقط استئناف بث Paused.

استمر في الإرسال بعد إيقاف مؤقت بسبب انخفاض التفاعل #

POST /broadcasts/{broadcastId}/override-engagement-guard

بينما يتم إرسال البث على دفعات، نقيس عدد الأشخاص الذين ردوا على كل دفعة قبل بدء الدفعة التالية. إذا لم يرد أحد تقريباً، يتوقف البث مؤقتاً من تلقاء نفسه — فعملية الإرسال التي تستمر في الدفع نحو الصمت هي أسرع طريقة ليتم تصفية الرقم أو حظره. إنه زر المتابعة على أي حال (Continue anyway) في لوحة التحكم.

نظراً لأن معدل الرد الذي تسبب في الإيقاف المؤقت لا يمكن أن يتغير أثناء توقف البث، فإن استئناف عادي سيؤدي فقط إلى إيقافه مؤقتاً مرة أخرى عند الفحص التالي. نقطة النهاية هذه هي قرار المتابعة على أي حال: فهي تسجل التجاوز على ذلك البث الواحد، وترفع الإيقاف المؤقت في نفس الاستدعاء إذا تم إيقاف البث مؤقتاً بسبب انخفاض التفاعل.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

الاستجابة (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — تم إيقاف البث مؤقتاً بسبب انخفاض التفاعل وهو يعمل الآن مرة أخرى؛ status هو المكان الذي تم استئنافه فيه.
• resumed: false — لم يتم رفع أي شيء، يتم تسجيل التجاوز ببساطة للفحوصات المستقبلية. هذا ما تحصل عليه إذا لم يتم إيقاف البث مؤقتاً مطلقاً، أو تم إيقافه مؤقتاً لسبب مختلف (قمت بإيقافه يدوياً، أو تم الوصول إلى حد الإرسال، أو حدث خطأ في الكثير من عمليات الإرسال). لا يتم رفع هذه الإيقافات المؤقتة هنا — قم باستئنافه بنفسك بمجرد التعامل مع السبب.

ينطبق التجاوز على هذا البث فقط. إنه ليس إعداداً للحساب، ومن الآمن استدعاؤه مرتين.

تكرار بث #

POST /broadcasts/{broadcastId}/duplicate — ينسخ الجمهور والرسالة والإعدادات إلى Draft جديد. كل شيء يتعلق بالتشغيل السابق (العدادات، الدفعات، الجدول الزمني، إحصائيات الرد) يبدأ من جديد.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

الاستجابة (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

لا ترث النسخة أبداً موافقة WhatsApp المباشرة: في نسخة WhatsApp، يأتي القالب وهو بحاجة إلى تأكيدك، وفي نسخة إلى قناة أخرى يتم إسقاطه ويصبح النص هو الفاتح العادي. النسخ إلى SMS يؤدي أيضاً إلى إسقاط أي مرفق، نظراً لأن SMS لا يمكنه إرسال واحد.

حذف بث #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

يتم رفض بث Sending أو Scheduled باستخدام 400 — قم بإيقافه مؤقتاً أولاً.

البث الذي يعكس حملة كلاسيكية #

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

• تعديل الجمهور أو الرسالة أو الجدول الزمني يعمل ويتم حفظه في الحملة.
• القناة، ووكيل الرد، والمرفق، وجميع عدادات التشغيل للقراءة فقط هنا — سيظهر 400 إذا حاولت تغييرها. قم بتغييرها في الحملة.
• الإطلاق (Launch) يعيد 400 يوجهك إلى محرر الحملة.
• الإيقاف المؤقت والاستئناف يعملان ويؤثران على الحملة.
• الحذف يعيد 400 — احذف الحملة بدلاً من ذلك، وسيتم حذف إدخال البث الخاص بها معها.
• التكرار (Duplicate) يمنحك بثاً أصلياً مستقلاً، وهي الطريقة المدعومة لنقل حملة أثبتت نجاحها.

الأخطاء #

الطلبات الفاشلة تعيد {"success": false, "error": "<message>"} مع الحالات التالية:

الخطوات التالية #

• دليل البث — المنتج الذي يقف خلف نقاط النهاية هذه، بما في ذلك سلوكيات التدرج والأمان
• واجهة برمجة تطبيقات جهات الاتصال — قم ببناء القائمة التي يرسل إليها البث
• واجهة برمجة تطبيقات القوالب — إدارة قوالب WhatsApp المعتمدة التي يمكنك الاختيار من بينها
• واجهة برمجة تطبيقات خطافات الويب (Webhooks) — اشترك في Broadcast Started و Broadcast Completed بدلاً من الاستطلاع (polling)