Broadcasts API #

שידור (broadcast) הוא שליחה אחת יוצאת: קהל יעד, הודעת פתיחה, ערוץ אחד ולוח זמנים. אופציונלית, הוא גם מציין את סוכן ה-AI שמטפל בתשובות שמתקבלות. ה-Broadcasts API מאפשר לך לבנות, לתמחר, להשיק ולנטר את השליחות האלו מהקוד שלך במקום מלוח הבקרה. למידע על המוצר עצמו, עיין במדריך השידורים.

• כתובת בסיס (Base URL) — https://api.youraiconnector.com/v1
• אימות (Authentication) — מפתח ה-API שלך (ראו אימות)
• שגיאות ועימוד (Errors & paging) — ראו שגיאות ועימוד

כל הדוגמאות להלן מציגות את טופס השאילתה ?apiKey= ב-cURL ואת הכותרת X-API-Key ב-JavaScript וב-Python — שתי הדרכים עובדות בכל נקודת קצה (endpoint).

בסייר ה-API. כל נקודת קצה (endpoint) בדף זה נמצאת במפרט ה-OpenAPI המפורסם, כך שתוכל לעיין בשדות המדויקים שלה ולהריץ בקשות חיות בסייר ה-API.

איך שליחה מורכבת #

שליחת שידור מורכבת מארבע קריאות, לא אחת:

1. יצירה (Create) של השידור עם קהל היעד, הערוץ ולוח הזמנים שלו — הוא מתחיל כ-Draft.
2. הגדרת הודעת הפתיחה. ב-WhatsApp Business זה אומר הגשת תבנית לאישור (או בחירת תבנית שכבר אושרה). בכל ערוץ אחר מדובר בטקסט פשוט.
3. הערכת העלות אם ברצונך לבדוק את המחיר לפני הוצאת כסף (אופציונלי).
4. השקה. השקה מריצה בדיקה מלאה — קהל יעד, הודעה, אישור תבנית, שולח מחובר — ואז או שמתחילה את השליחה או אומרת לך בדיוק מה חסר.

שום דבר לא נשלח עד שתקרא לפעולת ההשקה (launch).

אובייקט השידור #

{
  "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 (execution_date, created_at, last_modified_at, …), וכל הפניה לאיש קשר חוזרת כמחרוזת נתיב כמו contacts/uid_whatsapp_15551234567.

שדות שאתה מגדיר #

כל מה שתשלח כ-user_id, id, status או source_campaign_id יתעלמו ממנו ביצירה ויוסר בעדכון — הסטטוס עובר אך ורק דרך נקודות הקצה של השקה (launch), השהיה (pause) וחידוש (resume) להלן.

שדות שהפלטפורמה מתחזקת #

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": { ... } }. השתמש בו כדי לבצע תשאול (polling) של שליחה פעילה: 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 אישרה. השתמש באחד משני נקודות הקצה להלן.
• כל ערוץ אחר (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — ה-body של אותו שדה הוא פשוט הטקסט שנשלח. שליחתו דרך נקודת הקצה להלן שומרת אותו ומסמנת אותו כמוכן מבלי לערב את WhatsApp כלל.

הגשת תבנית לאישור #

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 הוא מה ש-WhatsApp מציגה: pending בזמן שהיא בבדיקה, approved כשהיא ניתנת לשימוש, rejected אם היא נדחתה. בערוץ שאינו WhatsApp היא חוזרת מיד כ-approved עם template_sid: null — אין מה לבדוק.

דברים שיעצרו אותך:

• הגשה בזמן שתבנית קודמת עדיין בבדיקה תחזיר 400. המתן להחלטה תחילה.
• עריכת תבנית שאושרה כרגע משאירה את התבנית המאושרת פעילה עד שהחדשה תחזור, כך ששידור פעיל לעולם לא מאבד את הפתיח שלו.
• במספר WhatsApp המחובר ישירות דרך 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 אם השידור אינו טיוטת WhatsApp, אם התבנית אינה מאושרת, אם מדובר בתבנית המשך ולא בפתיח, או אם לשידור יש קובץ מצורף (תבניות ספרייה הן טקסט בלבד). מזהה תבנית שאינו קיים בחשבונך יחזיר 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"

תגובת WhatsApp (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 לפני שתציג מספר. הוא מציין מי מחויב בתשלום:

SMS ללא פרטי התחברות של 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 בלוח הבקרה.

מכיוון ששיעור המענה שגרם להשהיה אינו יכול להשתנות בזמן שהשידור נעצר, resume פשוט יושעה שוב בבדיקה הבאה. נקודת קצה זו היא ההחלטה להמשיך בכל זאת: היא מתעדת את העקיפה באותו שידור, ומסירה את ההשהיה באותה קריאה אם השידור הושהה עקב מעורבות נמוכה.

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 — יש להשהות אותם תחילה.

שידורים המשקפים קמפיין קלאסי #

קמפיינים קלאסיים השולחים הודעות מופיעים גם בשידורים, וה-API מחזיר אותם לצד שידורים מקוריים (הם נושאים source_campaign_id). הם מתנהגים מעט אחרת, כיוון שהקמפיין נותר בשליטה:

• עריכת הקהל, ההודעה או התזמון עובדת ונרשמת ישירות בקמפיין.
• ערוץ, סוכן מענה, קובץ מצורף וכל מוני ההרצה הם לקריאה בלבד כאן — תקבל 400 אם תנסה לשנות אותם. שנה אותם בקמפיין.
• הפעלה (Launch) מחזירה 400 המפנה אותך לעורך הקמפיין.
• השהיה והמשך עובדים ומשפיעים על הקמפיין.
• מחיקה מחזירה 400 — מחק את הקמפיין במקום זאת, ורשומת השידורים שלו תימחק יחד איתו.
• שכפול מעניק לך שידור מקורי עצמאי, וזו הדרך הנתמכת להעברת קמפיין מוכח.

שגיאות #

בקשות שנכשלו מחזירות {"success": false, "error": "<message>"} עם הסטטוסים הבאים:

צעדים הבאים #

• מדריך שידורים — המוצר שמאחורי נקודות קצה אלו, כולל התנהגות קצב ובטיחות
• API אנשי קשר — בנה את הרשימה שאליה נשלח השידור
• API תבניות — נהל את תבניות ה-WhatsApp המאושרות שניתן לבחור מהן
• API Webhooks — הירשם ל-Broadcast Started ו-Broadcast Completed במקום לבצע סקר (polling)