# Broadcasts API
**שידור** (broadcast) הוא שליחה אחת יוצאת: קהל יעד, הודעת פתיחה, ערוץ אחד ולוח זמנים. אופציונלית, הוא גם מציין את סוכן ה-AI שמטפל בתשובות שמתקבלות. ה-Broadcasts API מאפשר לך לבנות, לתמחר, להשיק ולנטר את השליחות האלו מהקוד שלך במקום מלוח הבקרה. למידע על המוצר עצמו, עיין ב[מדריך השידורים](../broadcasts/broadcasts.md).
- **כתובת בסיס (Base URL)** — `https://api.youraiconnector.com/v1`
- **אימות (Authentication)** — מפתח ה-API שלך (ראו [אימות](authentication.md))
- **שגיאות ועימוד (Errors & paging)** — ראו [שגיאות ועימוד](errors-and-pagination.md)
כל הדוגמאות להלן מציגות את טופס השאילתה `?apiKey=` ב-cURL ואת הכותרת `X-API-Key` ב-JavaScript וב-Python — שתי הדרכים עובדות בכל נקודת קצה (endpoint).
> **בסייר ה-API.** כל נקודת קצה (endpoint) בדף זה נמצאת במפרט ה-OpenAPI המפורסם, כך שתוכל לעיין בשדות המדויקים שלה ולהריץ בקשות חיות ב[סייר ה-API](reference.md).
---
## איך שליחה מורכבת
שליחת שידור מורכבת מארבע קריאות, לא אחת:
1. **יצירה** (Create) של השידור עם קהל היעד, הערוץ ולוח הזמנים שלו — הוא מתחיל כ-`Draft`.
2. **הגדרת הודעת הפתיחה.** ב-WhatsApp Business זה אומר הגשת תבנית לאישור (או בחירת תבנית שכבר אושרה). בכל ערוץ אחר מדובר בטקסט פשוט.
3. **הערכת העלות** אם ברצונך לבדוק את המחיר לפני הוצאת כסף (אופציונלי).
4. **השקה.** השקה מריצה בדיקה מלאה — קהל יעד, הודעה, אישור תבנית, שולח מחובר — ואז או שמתחילה את השליחה או אומרת לך בדיוק מה חסר.
שום דבר לא נשלח עד שתקרא לפעולת ההשקה (launch).
---
## אובייקט השידור
```json
{
"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`.
### שדות שאתה מגדיר
| שדה | תיאור |
|---|---|
| `name` | איך השידור נקרא בלוח הבקרה. |
| `channel` | הערוץ היחיד שדרכו השידור נשלח: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. לשידור יש ערוץ אחד בדיוק — כדי לשלוח את אותו הדבר במקום אחר, [שכפל אותו לערוץ אחר](#duplicate-a-broadcast). `tiktok` ו-`skool` הם ערוצי מענה בלבד ולא ניתן לבצע דרכם שידורים. |
| `agent_id` | סוכן ה-AI שעונה לתשובות. השאר אותו `null` והתשובות יגיעו לתיבת הדואר הנכנס של הצוות שלך במקום. |
| `list_id` | רשימת אנשי הקשר לשליחה. כך מגדירים את קהל היעד מה-API — ראה [אנשי קשר](contacts.md) ליצירה ומילוי רשימות. |
| `list_name` | שם תצוגה שמופיע לצד השידור. קוסמטי בלבד. |
| `send_to_new_list_members` | `true` שומר על השידור פעיל כך שכל מי שיתווסף לרשימה מאוחר יותר יקבל גם הוא את הודעת הפתיחה. |
| `whats_app_template` | הודעת הפתיחה. ב-WhatsApp Business זו תבנית מאושרת אמיתית; בכל ערוץ אחר ה-`body` שלה משמש כטקסט הפתיחה הפשוט. הגדר זאת דרך [נקודות הקצה של התבניות](#the-opening-message), לא ידנית. |
| `opener_media` | תמונה או סרטון אחד שנשלחים עם הודעת הפתיחה. שלח תמיד את כל האובייקט (או `null` כדי להסירו) — כתיבת מפתחות בודדים בתוכו תידחה. לא נתמך ב-SMS. |
| `execution_date` | מתי לשלוח. שלח חותמת זמן בפורמט ISO 8601 או מילי-שניות בפורמט epoch. תאריך עתידי מתזמן את השליחה; השמט אותו (או השתמש בתאריך עבר) כדי לשלוח ברגע שתשיק. |
| `drip_mode` | `true` מבצע את השליחה במנות לאורך זמן במקום בבת אחת. |
| `time_critical` | `true` מוותר על התיזמון האוטומטי שמופעל מעל 50 אנשי קשר — עבור קהל חם שזקוק להודעה עכשיו. זה לא מסיר את מגבלת השליחה היומית של הערוץ עצמו. |
| `batch_size` | כמה אנשי קשר בכל מנה בעת שליחה מדורגת (dripping). |
| `follow_up_config` | שרשרת הודעות ההמשך עבור אנשי קשר שלעולם לא עונים. |
כל מה שתשלח כ-`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` (אנשי הקשר הבודדים שצורפו מלוח הבקרה, נקראים בחזרה כמחרוזות נתיב). קרא אותם, אל תכתוב אותם.
### סטטוסים
| Status | Meaning |
|---|---|
| `Draft` | Being built. Nothing is scheduled. |
| `Pending Approval` | Launched, but its WhatsApp template is still awaiting a decision. It starts sending on its own once the template is approved — you do not need to launch again. |
| `Scheduled` | Launched with a future `execution_date`. |
| `Sending` | Actively sending (a broadcast armed for new list members stays here while it waits for them). |
| `Paused` | Held — by you, or automatically by a safety check. |
| `Sent` | Finished. |
| `Failed` | Finished with more than half the sends failing. |
---
## יצירת שידור
`POST /broadcasts` — יוצר `Draft`.
**cURL**
```bash
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**
```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**
```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`)
```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```
---
## רשימת שידורים
`GET /broadcasts` — כל שידור בחשבון, מהחדש ביותר לישן ביותר.
**פרמטרים של שאילתה**
| פרמטר | נדרש | תיאור |
|---|---|---|
| `status` | לא | החזר רק שידורים בסטטוס אחד, למשל `Sending`. הקפד על איות מדויק כפי שמופיע ב[טבלת הסטטוסים](#statuses). |
```bash
curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"
```
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();
```
```python
res = requests.get(
"https://api.youraiconnector.com/v1/broadcasts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]
```
**תגובה** (`200`)
```json
{ "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` מתעדכנים תוך כדי תנועה.
```bash
curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"
```
שידור שאינו קיים בחשבונך מחזיר `404`.
---
## עדכון שידור
`PUT /broadcasts/{broadcastId}` — שלח רק את השדות שברצונך לשנות. באפשרותך גם לפנות למפתח יחיד בתוך אובייקט מקונן באמצעות נתיב מנוקד, למשל `"whats_app_template.body"`.
```bash
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" }'
```
```javascript
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`, מכיוון שקובץ מצורף שעודכן חלקית יתאר קובץ שאינו קיים.
- **לא ניתן לערוך סטטוס.** השתמש ב-[השקה](#launch-a-broadcast), [השהיה](#pause-and-resume) ו-[המשך](#pause-and-resume).
---
## הודעת הפתיחה
כל שידור נושא את הפתיח שלו ב-`whats_app_template`. המשמעות של זה תלויה בערוץ:
- **WhatsApp Business** — עליו להיות תבנית ש-WhatsApp אישרה. השתמש באחד משני נקודות הקצה להלן.
- **כל ערוץ אחר** (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — ה-`body` של אותו שדה הוא פשוט הטקסט שנשלח. שליחתו דרך נקודת הקצה להלן שומרת אותו ומסמנת אותו כמוכן מבלי לערב את WhatsApp כלל.
### הגשת תבנית לאישור
`POST /broadcasts/{broadcastId}/template`
| שדה | חובה | תיאור |
|---|---|---|
| `body` | כן | טקסט ההודעה, עד 1024 תווים. השתמש במקומות שמורים מסוג `{{variable}}` להתאמה אישית. |
| `name` | לא | שם התבנית. כברירת מחדל משתמש בשם השידור. |
| `language` | לא | קוד שפה. כברירת מחדל משתמש ב-`en`. |
| `category` | לא | `marketing` (ברירת מחדל), `utility`, `authentication`, או `authentication-international`. זהו התעריף לפיו מחוייבת השליחה, לכן הקפד על דיוק. |
| `variables` | לא | שמות המקומות השמורים, לפי סדר הופעתם. השאר ריק והם ייקראו מתוך גוף ההודעה — שזה בדרך כלל מה שתרצה, כיוון שהשליחה ממלאת אותם עבור כל איש קשר. |
```bash
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`)
```json
{ "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` — מעתיק תבנית שכבר אושרה מ[ספריית התבניות](templates.md) שלך אל השידור, כך שאין למה לחכות.
| שדה | חובה | תיאור |
|---|---|---|
| `template_id` | כן | המזהה (id) של תבנית מאושרת בחשבונך. |
```bash
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`)
```json
{
"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`, כיוון שההערכה סופרת את הקהל.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"
```
**תגובת WhatsApp** (`200`) — זיכויים, בחלוקה לפי מדינת יעד:
```json
{
"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 שלך:
```json
{
"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` לפני שתציג מספר.** הוא מציין מי מחויב בתשלום:
| `billing_mode` | מי משלם | מה המשמעות של הנתונים |
|---|---|---|
| `credits` | חשבון ה-Your AI Connector שלך | `totalTemplateCost` והנתונים לפי מדינה הם נקודות זכות (credits). |
| `twilio_direct` | חשבון ה-Twilio שלך | `estimatedCostUsd` הוא הסכום ש-Twilio תחייב אותך בו. |
| `meta_waba_direct` | חשבון ה-WhatsApp Business שלך, מחויב על ידי Meta | כל נתון של נקודות זכות חוזר כ-`null` — באופן מכוון, כדי שלעולם לא יתפרש בטעות כ"חינם". ספירות המדינות ואנשי הקשר עדיין מדויקות. |
SMS ללא פרטי התחברות של Twilio שחוברו עדיין מחזיר את ספירות המקטעים, עם `estimatedCostUsd: 0` — אין תמחור לבדיקה.
---
## הפעל שידור
`POST /broadcasts/{broadcastId}/launch`
ההפעלה בודקת הכל תחילה ורק אז מקדמת את השידור. אין הפעלה חלקית: או שהוא מתחיל, או ששום דבר לא משתנה ואתה מקבל שגיאה שמסבירה מדוע.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"
```
**JavaScript**
```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**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())
```
**תגובה** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }
```
`status` הוא המקום שבו השידור נחת:
- `Scheduled` — `execution_date` נמצא בעתיד.
- `Sending` — הוא התחיל עכשיו.
- `Pending Approval` — תבנית ה-WhatsApp עדיין בבדיקה. היא תישלח מעצמה ברגע שהתבנית תאושר; אל תפעיל את השיגור שוב.
ניתן להפעיל רק `Draft` (או שידור `Pending Approval` שהתבנית שלו אושרה מאז) — כל דבר אחר יחזיר `400`.
### מדוע שיגור מסורב
כל אחד מאלה חוזר כ-`400` עם הודעת `error` בשפה פשוטה:
| בעיה | מה לתקן |
|---|---|
| אין קהל יעד | הגדר `list_id` (או צרף אנשי קשר) לפני השיגור. |
| אין הודעת פתיחה | הגדר את הודעת הפתיחה — ראה [הודעת הפתיחה](#the-opening-message). |
| קובץ מצורף ב-SMS | SMS לא יכול לשאת תמונה או וידאו. הסר את הקובץ המצורף או העבר את השידור ל-WhatsApp. |
| הקובץ המצורף אינו תואם לתבנית המאושרת | ב-WhatsApp המדיה נמצאת בתוך התבנית המאושרת, לכן החלפת הקובץ המצורף לאחר מכן משמעותה הגשה מחדש של התבנית. |
| תבנית נדחתה | נסח מחדש את ההודעה והגש אותה שוב. |
| תבנית מעולם לא הוגשה | הגש אותה (או בחר תבנית מאושרת) תחילה. |
| תבנית אושרה אך חסרה בחשבון ה-WhatsApp שלך | בדרך כלל מדובר בתבנית שאושרה לפני שהמספר סיים להתחבר. הגש אותה שוב. |
| אין שולח מחובר לערוץ | חבר את הערוץ תחילה — ראה [ערוצים](channels.md). |
| ערוץ המיועד למענה בלבד | TikTok ו-Skool אינם מאפשרים לעסק להתחיל שיחה, לכן לא ניתן לבצע בהם שידורים. |
| כבר חמוש | לשידור כבר יש שליחה מתוזמנת. השהה אותו לפני הפעלה מחדש. |
| עדיין ממתין לאישור | הוא יישלח מעצמו כשהתבנית תאושר. |
| חשבון WhatsApp Business חסום על ידי Meta | Meta עצרה שיחות ביוזמת העסק בחשבון ה-WhatsApp Business שלך — בדרך כלל מדובר בבעיית אמצעי תשלום. תקן זאת ב-Meta Business Manager. |
| התחיל מקמפיין קלאסי | הפעל אותו מעורך הקמפיינים במקום זאת. ראה [קמפיינים קלאסיים בשידורים](#broadcasts-that-mirror-a-classic-campaign). |
---
## השהיה והמשך
`POST /broadcasts/{broadcastId}/pause` עוצר שידור `Sending` או `Scheduled` ומבטל כל מה שנמצא בתור.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"
```
השהיית שידור `Pending Approval` מחזירה אותו ל-`Draft` במקום זאת — שום דבר לא תוכנן עדיין, לכן אין למה להמשיך. כל סטטוס אחר מחזיר `400`.
`POST /broadcasts/{broadcastId}/resume` מפעיל מחדש שידור `Paused`:
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"
```
**תגובה** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```
הוא ממשיך ל-`Sending`, או חוזר ל-`Scheduled` אם ה-`execution_date` שלו עדיין בעתיד. ניתן להמשיך רק שידור `Paused`.
---
## המשך שליחה לאחר השהיה עקב מעורבות נמוכה
`POST /broadcasts/{broadcastId}/override-engagement-guard`
בזמן ששידור נשלח בקבוצות, אנו מודדים כמה אנשים השיבו לכל קבוצה לפני תחילת הבאה. אם כמעט אף אחד לא משיב, השידור מושהה מעצמו — שליחה שממשיכה לדחוף לתוך שתיקה היא הדרך המהירה ביותר לגרום למספר להיחסם או להיות מסונן. זהו כפתור ה-**Continue anyway** בלוח הבקרה.
מכיוון ששיעור המענה שגרם להשהיה אינו יכול להשתנות בזמן שהשידור נעצר, [resume](#pause-and-resume) פשוט יושעה שוב בבדיקה הבאה. נקודת קצה זו היא ההחלטה להמשיך בכל זאת: היא מתעדת את העקיפה באותו שידור, ומסירה את ההשהיה באותה קריאה אם השידור הושהה עקב מעורבות נמוכה.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"
```
**תגובה** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }
```
- `resumed: true` — השידור הושהה עקב מעורבות נמוכה וכעת הוא פועל שוב; `status` היא הנקודה שבה הוא התחדש.
- `resumed: false` — שום דבר לא הוסר, העקיפה פשוט מתועדת לבדיקות עתידיות. זה מה שתקבל אם השידור מעולם לא הושהה, או שהושהה מסיבה אחרת (השהית אותו ידנית, הגעת למכסת שליחה, או ששליחות רבות נכשלו). השהיות אלו אינן מוסרות כאן — עליך לחדש את השידור בעצמך לאחר שתטפל בסיבה.
העקיפה חלה על שידור זה בלבד. זו אינה הגדרת חשבון, ובטוח לקרוא לה פעמיים.
---
## שכפול שידור
`POST /broadcasts/{broadcastId}/duplicate` — מעתיק את הקהל, ההודעה וההגדרות ל-`Draft` חדש. כל מה שקשור להרצה הקודמת (מונים, אצוות, תזמון, נתוני תגובות) מתחיל מחדש.
| שדה | נדרש | תיאור |
|---|---|---|
| `to_channel` | לא | צור את העותק בערוץ אחר. כך ניתן לשלוח את אותו הדבר בשני ערוצים — לשידור יש תמיד ערוץ אחד בלבד. |
```bash
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`)
```json
{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }
```
עותק לעולם אינו יורש אישור WhatsApp פעיל: בעותק WhatsApp התבנית עוברת כשהיא זקוקה לאישורך, ובעותק לערוץ אחר היא מוסרת והטקסט הופך לפתיח רגיל. העתקה ל-SMS גם מסירה כל קובץ מצורף, מכיוון ש-SMS אינו יכול לשלוח כאלו.
---
## מחיקת שידור
`DELETE /broadcasts/{broadcastId}`
```bash
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": ""}` עם הסטטוסים הבאים:
| סטטוס | משמעות |
|---|---|
| `400` | משהו בבקשה או במצב השידור אינו תקין — שדה חסר, קובץ מצורף לא חוקי, או פעולת הפעלה/השהיה/המשך/מחיקה שאינה מותרת במצב הנוכחי של השידור. ההודעה `error` מציינת את הסיבה. |
| `401` | מפתח API חסר או לא חוקי. |
| `403` | התוכנית שלך אינה כוללת גישת API. |
| `404` | אין שידור כזה בחשבונך (או, בבחירת תבנית, אין תבנית כזו). |
| `429` | הגבלת קצב (Rate limited). המתן ונסה שוב. |
| `500` | משהו השתבש בצד שלנו. נסה שוב לאחר המתנה קצרה. |
---
## צעדים הבאים
- [מדריך שידורים](../broadcasts/broadcasts.md) — המוצר שמאחורי נקודות קצה אלו, כולל התנהגות קצב ובטיחות
- [API אנשי קשר](contacts.md) — בנה את הרשימה שאליה נשלח השידור
- [API תבניות](templates.md) — נהל את תבניות ה-WhatsApp המאושרות שניתן לבחור מהן
- [API Webhooks](webhooks.md) — הירשם ל-`Broadcast Started` ו-`Broadcast Completed` במקום לבצע סקר (polling)