# Campaigns API

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

כל נקודות הקצה להלן הן יחסיות לכתובת ה-URL הבסיסית `https://api.youraiconnector.com/v1`. כל בקשה חייבת לעבור אימות — עיין ב-[API Access](../integrations/api-access.md) וב-[Authentication](authentication.md) כדי ללמוד כיצד להשיג ולהעביר את מפתח ה-API שלך. גישת API היא תכונה בתשלום; ללא גישה זו, בקשות יידחו עם `403`.

> **שים לב:** חלק מהדוגמאות מציגות את טופס השאילתה הפשוט `?apiKey=YOUR_API_KEY`, ואחרות משתמשות בכותרת `X-API-Key`. שתיהן עובדות בכל מקום — השתמש במה שמתאים להגדרה שלך.

---

## סוגי קמפיינים

כאשר יוצרים קמפיין, יש לבחור באחד מהסוגים הבאים:

| סוג | למה זה מיועד |
|---|---|
| `Incoming from Unknown Contacts` | הבוט משיב לאנשים ששולחים לך הודעה בפעם הראשונה. |
| `Outgoing` | הבוט מתחיל שיחות עם אנשי קשר שאתה מוסיף לקמפיין. |
| `Keywords` | **לא פעיל - אין להשתמש.** קמפיין מסוג `Keywords` אינו פעיל: הוא עדיין נתמך לצורך תאימות לאחור, אך הוא אינו גלוי לניתוב נכנס באף ערוץ ואף אחד לא קורא את מילות המפתח המפעילות שלו. השתמש בנקודת כניסה (Entry Point) מסוג **מילת מפתח** (Keyword) בסוכן AI במקום זאת. |
| `Combined` | שילוב של התנהגות נכנסת ויוצאת. |

**אין חשיבות לרישיות (אותיות גדולות/קטנות).** `type`, `status`, `booking_provider`, `first_response_mode`, `bot.anthropic_model` ו-`bot.ai_speed` מקבלים את כל סוגי הרישיות — `"live"`, `"Live"` ו-`"LIVE"` הם אותו הדבר — והערך נשמר בצורתו הקנונית, שהיא הערך שיוחזר בעת קריאת הקמפיין. החריג היחיד הוא זוג ההשהיה: `"Paused"` ו-`"paused"` הם שני מצבים שונים באמת, לכן איות דו-משמעי כמו `"PAUSED"` נדחה עם `400` המנחה אותך לבחור באחד מהם.

### שני מצבי ההשהיה

| סטטוס | מי כותב אותו | מה זה אומר |
|---|---|---|
| `Paused` | בדיקות הבטיחות של הפלטפורמה עצמה (מעורבות נמוכה, שגיאות שליחה חוזרות, הגעה למכסה) ומשטחי ה-Agents וה-Broadcasts החדשים יותר | הקמפיין מושהה. סריקה מתוזמנת יכולה לבטל השהיית בטיחות באופן אוטומטי ברגע שהסיבה נעלמת. |
| `paused` | כפתור ה-Pause בלוח הבקרה, יחד עם `resumed` ב-Resume | אדם השהה זאת ידנית. שליחות מתוזמנות מפורקות ונבנות מחדש בעת החידוש. |

שניהם עוצרים את הקמפיין: ניתוב נכנס פועל רק כאשר הסטטוס הוא בדיוק `Live`. **מה-API, השתמש ב-`Paused` כדי להשהות וב-`Live` כדי לחדש** — זוג האותיות הקטנות קיים עבור כפתור לוח הבקרה ונשמר פעיל עבורו.

אף אחד מאלה אינו מה שקורה כאשר ה-AI מפסיק להשיב בתוך שיחה אחת. זהו מתג לכל איש קשר, `is_bot_active` על איש הקשר — מוגדר כאשר אדם משתלט, כאשר איש הקשר מבטל הסכמה, או כאשר ה-AI מסיים את הצ'אט. הסטטוס של הקמפיין עצמו נותר ללא שינוי, וכל שיחה אחרת בו ממשיכה לפעול. ראה [השהיה או חידוש של ה-AI עבור איש קשר אחד](messages.md#pause-or-resume-the-ai-for-one-contact).

> **יצירת קמפיין אינה קובעת מי עונה לערוץ.** הניתוב מנוהל על ידי **נקודות כניסה** (Entry Points) בסוכן AI, לא על ידי קמפיינים. לכל ערוץ יש נקודת כניסה אחת המוגדרת כברירת מחדל לערוץ, המציינת את הסוכן שעונה לאנשי קשר חדשים ולא מוכרים בו: הגדר אותה באמצעות `PUT /entry-points/channel-defaults`, בדוק אם הסולם פעיל עבור החשבון עם `GET /entry-points/routing-status`, נקה אותה עם `DELETE /entry-points/channel-defaults`. `POST /channels/campaign` עדיין כותב את מפת ניתוב הקמפיינים הישנה לפי ערוץ, אך מפה זו כבר אינה נבדקת עבור ניתוב נכנס באף חשבון; היא נשמרת לצורך שחזור בלבד. אל תבנה על בסיסה. ראה [ניתוב ערוץ לקמפיין](channels.md#route-a-channel-to-a-campaign) עבור שני הממשקים זה לצד זה.

---

## רשימת קמפיינים

`GET /campaigns`

מחזיר את הקמפיינים שלך, מהחדש ביותר לישן ביותר. קמפיינים מאורכבים אינם נכללים אלא אם תעביר `archived=true`.

**פרמטרים של שאילתה**

| פרמטר | נדרש | תיאור |
|---|---|---|
| `limit` | לא | מספר מקסימלי של קמפיינים להחזרה. ברירת המחדל היא `50`, המקסימום הוא `100`. |
| `cursor` | לא | סמן דפדוף (Pagination cursor). העבר את הערך `next_cursor` מהתגובה הקודמת כדי לקבל את הדף הבא. |
| `archived` | לא | הגדר ל-`true` כדי לכלול קמפיינים מאורכבים. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])
```

**תגובה**

```json
{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}
```

כאשר `next_cursor` הוא `null`, הגעת לעמוד האחרון.

---

## קבלת קמפיין

`GET /campaigns/{campaignId}`

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

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]
```

**תגובה**

```json
{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}
```

::: note
**הערה:** קמפיין שבבעלות חשבון אחר מחזיר `404 Campaign not found` (ולא `403`), לכן לא ניתן לדעת אם מזהה קיים בחשבון אחר.
:::


---

## יצירת קמפיין

`POST /campaigns`

יוצר קמפיין חדש. `name` ו-`type` הם שדות חובה; כל השאר אופציונליים. ניתן לכלול כל שדה קמפיין אחר באותה בקשה — לדוגמה `language`, `ai_mode`, או אובייקט הגדרות `bot` מלא — והוא יישמר עם הקמפיין החדש. הבעלים וזמן היצירה נקבעים באופן אוטומטי.

**שדות הבקשה**

| שדה | חובה | תיאור |
|---|---|---|
| `name` | כן | שם הקמפיין. |
| `type` | כן | אחד מארבעת סוגי הקמפיינים שלעיל. |
| `language` | לא | השפה שבה הבוט משיב (למשל `"en"`). |
| `ai_mode` | לא | האם מצב AI מופעל (`true`/`false`). בקמפיין שנענה על ידי סוכן AI, קריאות מחזירות את מצב ה-**Active** של הסוכן במקום ערך שמור — ראו את ההערה תחת עדכון להלן. |
| `bot` | לא | אובייקט הגדרות הבוט (ראו [שדות הגדרת בוט](#bot-configuration-fields)). |
| `list_id` | לא | מזהה (ID) של רשימת אנשי הקשר לצירוף. |
| `event_id` | לא | מזהה (ID) של סוג האירוע שה-AI רשאי לקבוע. |
| `event_ids` | לא | מספר סוגי אירועים בבת אחת, כמערך של מזהי סוגי אירועים — הראשון הוא ברירת המחדל. שלחו או את `event_id` או את `event_ids`, לא את שניהם. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

---

## עדכון קמפיין

`PUT /campaigns/{campaignId}`

מעדכן קמפיין באופן חלקי — שלח רק את השדות שברצונך לשנות. זהו פועל העדכון הכללי היחיד; אין `PATCH /campaigns/{campaignId}` (שני נתיבי ה-`PATCH` הם מתגי ה-[enable](#enable-or-disable-a-campaign) וה-[archive](#archive-or-restore-a-campaign) המצומצמים).

**אילו שדות ניתן לשנות.** כל מה שעורך הקמפיין כותב, כולל `name`, `status`, `type`, `language`, `ai_mode`, `enabled_channels`, הגדרות הטריגר וה-drip, דגלי ההזמנות והמעקב, שדות הניטור של אינסטגרם/פייסבוק, וכל הגדרת ה-`bot`. זהות ובעלות נעולים לכל אורך חיי הקמפיין: `user`, `id`, ו-`created_at` נדחים, וכך גם כל שם שדה שה-endpoint אינו מזהה. הדחייה היא לפי בקשה, לא לפי שדה — מפתח אחד לא ידוע מחזיר `400` ו**שום דבר** באותה בקשה לא נכתב.

**`ai_mode` בקמפיין המגובה על ידי סוכן משקף את הסוכן.** כאשר קמפיין נענה על ידי סוכן AI, קריאת הקמפיין מחזירה את `ai_mode` הנגזר מהמתג **Active** (פעיל) של אותו סוכן — המתג היחיד שקובע בפועל אם ה-AI ישיב. כתיבת `ai_mode` בקמפיין כזה תתקבל, אך לא תשנה את הערך שיוחזר בקריאה; במקום זאת, יש להפעיל או לכבות את מתג ה-Active של הסוכן (בלוח הבקרה, או דרך ה-API של הסוכנים). בקמפיינים קלאסיים ללא סוכן, `ai_mode` קורא וכותב את הערך השמור כפי שהיה קודם לכן.

**שדות בוט מתמזגים, הם לא נדרסים.** שלח הגדרות בוט כמפתחות עם נקודות (`"bot.instructions": "..."`) או כאובייקט מקונן (`"bot": { "instructions": "..." }`) — שניהם כותבים עלה אחר עלה, כך שהשדות שאתה משמיט שומרים על הערכים הנוכחיים שלהם. `bot.instructions`, `bot.goal`, `bot.rules`, ו-`bot.personality` ניתנים כולם לעריכה בדרך זו, וכך גם כל הגדרת בוט אחרת המפורטת תחת [שדות הגדרת בוט](#bot-configuration-fields). אותו דבר חל על `test_bot`, `frequency`, ו-`follow_up_config`.

כדי להחליף הגדרת בוט באופן מלא — מחיקת כל שדה שאינך שולח — השתמש ב-`bot_replace` (או `test_bot_replace`) עם האובייקט המלא. לא ניתן לשלב החלפה ומיזוג עבור אותו אובייקט בבקשה אחת; זה מחזיר `400`.

::: note
**הערה:** כתיבת `bot.*` דרך ה-API נכנסת לתוקף **באופן מיידי** בקמפיין החי. עורך לוח הבקרה עובד אחרת: עריכות שם נשמרות כטיוטה ועולות לאוויר רק כאשר הלקוח לוחץ על Publish. לכן, אם ללקוח יש שינויים בלוח הבקרה שלא פורסמו, הם יושבים ב-`test_bot` וקריאת API של `bot` מציגה נכון את מה שה-AI משתמש בו כרגע.
:::


מספר שדות מוגדרים באמצעות מפתח ייעודי במקום להיכתב ישירות: השתמשו ב-`list_id` עבור רשימת אנשי הקשר, ב-`event_id` עבור סוג האירוע (או ב-`event_ids`, מערך סדור של מזהי סוגי אירועים, כדי לאפשר ל-AI לקבוע כמה — הראשון הוא ברירת המחדל; מערך ריק ינתק את כולם), וב-`contact_ids` (מערך של מזהי אנשי קשר) עבור אנשי הקשר של הקמפיין. רשומות בסיס הידע מנוהלות דרך ה-[FAQs API](faqs.md), ולא דרך נקודת קצה זו.

**תגיות מחליפות, הן לא מתמזגות.** שלח את `tags` כמערך המלא והוא יהפוך לקבוצת התגיות של הקמפיין — ראה [תגיות קמפיין](#campaign-tags) עבור השדות ועבור נקודות הקצה שמוסיפות או עורכות תגית בודדת.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

---

## מחיקת קמפיין

`DELETE /campaigns/{campaignId}`

מוחק קמפיין לצמיתות. פעולה זו אינה ניתנת לביטול — אם ייתכן שתזדקק לקמפיין שוב בעתיד, [ארכב אותו](#archive-or-restore-a-campaign) במקום.

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true
}
```

---

## שכפול קמפיין

`POST /campaigns/{campaignId}/duplicate`

יוצר עותק של הקמפיין עם כל ההגדרות שלו כפי שהן. העותק מתחיל במצב **מושבת** ושמו מקבל סיומת `(copy)`, כך שהוא לעולם לא ישלח הודעות עד שתפעיל אותו במפורש.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}
```

> עותקים כפולים **בתוך חשבון אחד**.

---


## הפעלה או השבתה של קמפיין

`PATCH /campaigns/{campaignId}/enabled`

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

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `enabled` | כן | `true` כדי להפעיל, `false` כדי להשבית. חייב להיות בוליאני. |

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}
```

---

## ארכוב או שחזור של קמפיין

`PATCH /campaigns/{campaignId}/archived`

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

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `archived` | כן | `true` כדי לארכב, `false` כדי לשחזר. חייב להיות בוליאני. |

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}
```

---

## עדכון הגדרות הבוט

`PUT /campaigns/{campaignId}/bot-config`

זוהי הדרך הבטוחה לשינוי הגדרות בוט בודדות. כל שדה שתשלח **ימוזג** לתוך הגדרות הבוט הקיימות, כך שכל שדה שתשמיט יישמר כפי שהיה. השתמש בשיטה זו במקום בנקודת הקצה של עדכון הקמפיין (campaign-update) בכל פעם שברצונך לבצע שינוי חלקי בלבד בבוט.

מפתחות שדות חייבים להכיל אותיות, מספרים, קווים תחתונים ומקפים בלבד.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

### שדות הגדרות הבוט

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

| שדה | סוג | תיאור |
|---|---|---|
| `instructions` | string | ההנחיות העיקריות שמכוונות את אופן הדיבור של הבוט עם אנשי קשר. |
| `rules` | string | חוקים נוקשים שהבוט חייב לציית להם תמיד. |
| `goal` | string | התוצאה שהבוט צריך לשאוף אליה בכל שיחה. |
| `personality` | string | תיאור טון הדיבור והאישיות של הבוט. |
| `ai_speed` | string | כמה הסקה (reasoning) ה-AI מיישם לפני השבה. אחד מתוך `fast`, `fast_thinker`, `balanced`, `thorough`. |
| `anthropic_model` | string | רמת האיכות של ה-AI המשמשת לתשובות של קמפיין זה. אחד מתוך `standard`, `economy` (לא מומלץ), `max`, `mini`. `max` ו-`mini` נכנסים לתוקף רק בחשבונות הזכאים לרמות אלו. |
| `max_messages` | integer | מספר הודעות הבוט המקסימלי לכל שיחה. |
| `alert_human_when` | string | תנאים שבהם הבוט צריך להתריע בפני איש צוות אנושי. |
| `availability` | object | לוח הזמנים של שעות הפעילות של הבוט. ניתן להגדיר זאת כאן, או להשתמש ב-[נקודת קצה של שעות פעילות](#set-the-bot-active-hours) הייעודית. |
| `follow_up_config` | object | הגדרת התנהגות המשך (Follow-up), נשמרת כפי שסופקה. |

---

## הגדרת שעות הפעילות של הבוט

`PUT /campaigns/{campaignId}/active-hours`

מגדיר את לוח הזמנים של זמינות הבוט. מחוץ לחלונות הזמן שהוגדרו, הבוט לא ישיב באופן אוטומטי. פעולה זו כותבת את השדה `availability` בהגדרות הבוט.

**שדות הבקשה**

| שדה | נדרש | תיאור |
|---|---|---|
| `availability` | כן | אובייקט עם מפתחות לפי ימי השבוע. המפתחות המותרים הם `monday` עד `sunday`; כל מפתח אחר יחזיר `400`. ימים שלא יצוינו יישארו ללא שינוי. |

כל יום בשבוע מכיל חלון זמן בודד או מערך של חלונות. לחלון יש `start_time` ו-`end_time` בפורמט `HH:MM` של 24 שעות.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

---

## הצגת הפונקציות המותאמות אישית של קמפיין

`GET /campaigns/{campaignId}/custom-functions`

מחזיר את הפונקציות המותאמות אישית המקושרות לקמפיין זה, כשהן פתורות להגדרות מלאות. פונקציות מותאמות אישית הן פעולות HTTP חיצוניות שהבוט יכול להפעיל במהלך שיחה — למשל, בדיקת מלאי בחנות שלך או יצירת רשומה ב-CRM שלך.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]
```

**תגובה**

```json
{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}
```

---

## קישור פונקציה מותאמת אישית לקמפיין

`POST /campaigns/{campaignId}/custom-functions`

מקשר [פונקציה מותאמת אישית](../ai-automation/custom-functions.md) קיימת לקמפיין זה, כך שהבוט יוכל להפעיל אותה במהלך שיחה. קישור פונקציה שכבר מקושרת לא מבצע שום פעולה.

| שדה | נדרש | תיאור |
|---|---|---|
| `custom_function_id` | כן | מזהה (ID) של הפונקציה המותאמת אישית לקישור. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}
```

---

## ביטול קישור של פונקציה מותאמת אישית מקמפיין

`DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}`

ביטול קישור של פונקציה שאינה מקושרת לא מבצע שום פעולה.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}
```

---

## קישור מקור בסיס ידע לקמפיין

`POST /campaigns/{campaignId}/kb-sources`

מקשר מקור בסיס ידע (שנוצר באמצעות [API של שאלות נפוצות](faqs.md)) לקמפיין זה, כך שהבוט יוכל להסתמך עליו בעת מתן תשובות. קישור מקור שכבר מקושר לא מבצע שום פעולה.

| שדה | נדרש | תיאור |
|---|---|---|
| `kb_source_id` | כן | מזהה (ID) של מקור בסיס הידע לקישור. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}
```

---

## ביטול קישור של מקור בסיס ידע מקמפיין

`DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}`

ביטול קישור של מקור שאינו מקושר לא מבצע שום פעולה.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}
```

---

## קישור שרת MCP לקמפיין

`POST /campaigns/{campaignId}/mcp-servers`

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

| שדה | נדרש | תיאור |
|---|---|---|
| `mcp_server_id` | כן | מזהה שרת ה-MCP לקישור. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}
```

---

## ביטול קישור של שרת MCP מקמפיין

`DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}`

ביטול קישור של שרת שאינו מקושר לא מבצע שום פעולה.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}
```

---

## ספריית המדיה של הקמפיין

ספריית המדיה מכילה תמונות, סרטונים, מסמכים והודעות קוליות שהבוט יכול לשלוח במהלך שיחה.

### הצגת ספריית המדיה של קמפיין

`GET /campaigns/{campaignId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}
```

`media_url` הוא כתובת URL חתומה שנתפסה בזמן ההעלאה — ייתכן שהיא כבר פגה עד שתקרא אותה בחזרה; לוח הבקרה חותם אותה מחדש לפי דרישה.

### העלאת פריט מדיה

`POST /campaigns/{campaignId}/media-library`

| שדה | נדרש | תיאור |
|---|---|---|
| `base64Data` | כן | הקובץ, מקודד ב-base64 (ללא קידומת data-URL). |
| `mimeType` | כן | סוג ה-MIME של הקובץ (למשל `image/png`). |
| `title` | כן | תווית קצרה המוצגת בספרייה ובהנחיית ה-AI. |
| `description` | כן | הוראה המציינת לבוט **מתי** לשלוח פריט זה. |
| `fileName` | לא | שם קובץ מקורי, משמש לבניית שם אובייקט האחסון. |
| `sendMessage` | לא | ניסוח מועדף שהבוט צריך להשתמש בו כשהוא שולח פריט זה. |
| `maxSendsPerConversation` | לא | מספר פעמים מקסימלי שהבוט רשאי לשלוח פריט זה לאיש קשר אחד בשיחה. ברירת המחדל היא `1`. |
| `sendAsVoiceNote` | לא | עבור העלאת אודיו, המר אותו להודעה קולית ב-WhatsApp. ברירת המחדל היא `false` (נשמר כקובץ אודיו רגיל). |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'
```

**תגובה**

```json
{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}
```

### עדכון פריט מדיה

`PATCH /campaigns/{campaignId}/media-library/{itemId}`

עורך את המטא-נתונים של הפריט בלבד — כדי להחליף את הקובץ עצמו, מחק את הפריט והעלה אחד חדש.

| שדה | תיאור |
|---|---|
| `title` | תווית קצרה. |
| `description` | הוראה לגבי מתי לשלוח. |
| `send_message` | ניסוח מועדף לשימוש על ידי הבוט. |
| `max_sends_per_conversation` | מספר שלם אי-שלילי, או `null` כדי לנקות את המכסה. |

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}
```

### מחיקת פריט מדיה

`DELETE /campaigns/{campaignId}/media-library/{itemId}`

מחיקת פריט שכבר אינו קיים היא פעולה ללא השפעה (no-op).

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{ "success": true, "deleted": true }
```

---

## תגיות קמפיין

תגית קמפיין היא תווית שאתה מלמד את הבוט להחיל על איש קשר במהלך שיחה — `hot-lead`, `not-interested`, `booked-a-call`. לכל תגית יש שלושה חלקים:

| שדה | סוג | תיאור |
|---|---|---|
| `name` | string, נדרש | התווית עצמה. זה מה שהבוט מחיל על איש הקשר ומה שאתה מתאים אליו מאוחר יותר, לכן שמור עליו קצר ויציב. |
| `description` | string | ההוראה שאומרת לבוט **מתי** להחיל את התגית הזו. זה החלק שמבצע את העבודה — "האדם מאשר שהוא הצטרף לקהילה" יתקבל, "ליד חם" לא. |
| `webhook` | string | כתובת URL שמקבלת `POST` ברגע שהתגית מוחלת על איש קשר. השאר ריק אם אינך זקוק לכך. |
| `tag_id` | string | אופציונלי. מקשר את הערך הזה לתגית קיימת בחשבונך במקום ליצור חדשה. ספק זאת אם ברצונך להתייחס לתגית ספציפית זו מאוחר יותר באמצעות נקודות הקצה של תגית בודדת להלן. |

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

### הגדר את כל התגיות של קמפיין

`PUT /campaigns/{campaignId}` עם מערך `tags`.

פעולה זו מחליפה את התגיות של הקמפיין בדיוק במה שאתה שולח, שזה אותו דבר שהכרטיסייה 'תגיות' בלוח הבקרה עושה כשאתה שומר אותה. **שלח את המערך המלא בכל פעם** — תגית שאתה משמיט היא תגית שמחקת. שליחת `[]` מוחקת את כולן.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

קרא את התגיות בחזרה עם [`GET /campaigns/{campaignId}`](#get-a-campaign).

### הוסף תגית אחת

`POST /campaigns/{campaignId}/tags`

מוסיף תגית בודדת מבלי לשלוח מחדש את השאר. השתמש בזה כשאתה מוסיף לקבוצה שלא בנית בבקשה זו.

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'
```

פרסום אותה תגית בדיוק פעמיים לא עושה דבר בפעם השנייה. פרסום אותו `tag_id` עם שם או תיאור שונים מוסיף ערך **שני** במקום לערוך את הראשון — השתמש בנקודת הקצה להלן כדי לערוך במקום.

### עדכן או הסר תגית אחת

`PUT /campaigns/{campaignId}/tags/{tagId}`
`DELETE /campaigns/{campaignId}/tags/{tagId}`

אלו מתייחסים לרשומה אחת לפי ה-`tag_id` שלה, לכן הם עובדים רק על תגיות שנוצרו עם כזו. אם לתגית אין `tag_id`, שנה אותה באמצעות ה-`PUT /campaigns/{campaignId}` של המערך כולו לעיל.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'
```

‏`tagId` שאינו נמצא בקמפיין מחזיר `404` עם `"Tag not found in campaign tags"`.

---

## החלפת ערוצי קמפיין

`POST /campaigns/{campaignId}/channels`

מוסיף או מסיר ערוצים ממערך ה-`enabled_channels` של הקמפיין מבלי לשלוח מחדש את המערך כולו — בטוח יותר מאשר [`PUT /campaigns/{campaignId}`](#update-a-campaign) כאשר ייתכן שגורם אחר עורך את הקמפיין באותו הזמן.

שלח החלפה בודדת או אצווה — לא את שניהם באותה בקשה:

```json
{ "channel": "whatsapp", "action": "add" }
```

```json
{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }
```

| שדה | תיאור |
|---|---|
| `channel` | ערוץ אחד להחלפה. צרף עם `action`. |
| `action` | `"add"` או `"remove"`. צרף עם `channel`. |
| `add` | מערך ערוצים להוספה. טופס אצווה — השתמש במקום `channel`/`action`. |
| `remove` | מערך ערוצים להסרה. טופס אצווה. |

ערוצים תקפים: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `chat_widget`, `custom_channel`, `imessage`, `telegram`, `instagram_private`, `line`, `viber`, `tiktok`, `email`, `linkedin`, `skool`.

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}
```

> פעולה זו משנה רק באילו ערוצים הקמפיין מפורסם — היא לא קובעת מי עונה לערוץ. ראה [סוגי קמפיינים](#campaign-types) לעיל ו-[ניתוב קמפיין לערוצים נכנסים](#route-a-campaign-to-incoming-channels) להלן עבור כך.

---

## תגובה להודעה פרטית (אינסטגרם ופייסבוק)

תגובה להודעה פרטית (Comment-to-DM) הופכת תגובה באחד הפוסטים שלך לשיחה פרטית: מישהו מגיב, הבוט שולח לו הודעה פרטית (DM), והקמפיין ממשיך את השיחה משם. התכונה מוגדרת במלואה דרך אובייקט הקמפיין, כך שאין לה ממשק משתמש ייעודי.

חבר תחילה את דף הפייסבוק — ראה [חיבור ערוץ](channels.md#instagram--messenger-meta). לאחר מכן הגדר את השדות להלן באמצעות [`PUT /campaigns/{campaignId}`](#update-a-campaign).

> **הקמפיין חייב להיות `Live`.** ניטור תגובות אוסף רק קמפיינים שה-`status` שלהם הוא `Live` (ללא חשיבות לרישיות — ראה [סוגי קמפיינים](#campaign-types)). כל סטטוס אחר משבית אותו בשקט, וסטטוס מומצא כמו `"Active"` נדחה כעת עם `400` במקום להישמר. סטטוסים תקפים כוללים את `Draft`, `Pending Approval`, `Scheduled`, `Live`, `Paused`, `Completed`, `Sent` ו-`Failed`.

**שדות**

| שדה | סוג | תיאור |
|---|---|---|
| `monitor_instagram_posts` | boolean | עקוב אחר כל פוסט באינסטגרם בדף המחובר. |
| `instagram_post_ids` | string[] | עקוב רק אחר פוסטים אלו באינסטגרם. השאר ריק כאשר `monitor_instagram_posts` מופעל. |
| `instagram_comment_delay_minutes` | number | המתן מספר דקות זה לאחר תגובה לפני שליחת ההודעה הישירה (DM). |
| `monitor_facebook_posts` | boolean | עקוב אחר כל פוסט בפייסבוק בדף המחובר. |
| `facebook_post_ids` | string[] | עקוב רק אחר פוסטים אלו בפייסבוק. |
| `facebook_comment_delay_minutes` | number | השהיה לפני שליחת ההודעה הישירה, בדקות. |
| `public_comment_reply_instructions` | string | הנחיה עבור התגובה הגלויה שנותרה על הפוסט עצמו. דורס את ברירת המחדל של הניסוח "בדוק את ההודעות הישירות שלך". |
| `first_response_mode` | string | `"ai"` (ברירת מחדל) מייצר את ההודעה הישירה הראשונה ואת התגובה הציבורית. `"exact_text"` שולח את הניסוח שלך כפי שהוא, ללא יצירה על ידי בינה מלאכותית וללא חיוב קרדיט. |
| `first_response_exact_text` | string | ההודעה הישירה הראשונה כפי שהיא, בשימוש כאשר `first_response_mode` הוא `"exact_text"`. נדרש כדי שמצב זה ייכנס לתוקף. |
| `first_response_exact_text_variants` | string[] | ניסוחים נוספים עבור ההודעה הישירה הראשונה. אחד נבחר באקראי עבור כל שליחה, כך שהודעות חוזרות אינן זהות בתוכנן. |
| `public_comment_reply_exact_text` | string | התגובה הציבורית כפי שהיא במצב `"exact_text"`. השאר ריק כדי לדלג על התגובה הציבורית ולשלוח רק את ההודעה הישירה. |
| `public_comment_reply_exact_text_variants` | string[] | ניסוחים נוספים עבור התגובה הציבורית. |
| `monitor_instagram_followers` | boolean | התייחס לעוקב חדש כטריגר ושלח הודעה ישירה ראשונית (חשבונות אינסטגרם אישיים). |
| `follower_outreach_instructions` | string | הנחיה עבור הודעה ישירה ראשונית זו לעוקב חדש. |
| `respond_to_instagram_story_replies` | boolean | האם הבינה המלאכותית עונה לתגובות על הסטוריז שלך באינסטגרם. ברירת מחדל `true`. הגדר את `false` כדי שתגובות לסטורי יגיעו לצ'אט (עם הסטורי מצורף) ללא מענה של בינה מלאכותית. הגדרה חיה - אינה חלק מהטיוטה, לכן אין צורך לפרסם אותה. |

**ניקוי שדה**

שדות אלו מוסרים במקום להיות מוגדרים כ-`null` כאשר אתה שולח `null`, כך שהבוט חוזר לברירות המחדל שלו: `instagram_post_ids`, `facebook_post_ids`, `instagram_comment_delay_minutes`, `facebook_comment_delay_minutes`, `public_comment_reply_instructions`, `follower_outreach_instructions`, `first_response_exact_text`, `first_response_exact_text_variants`, `public_comment_reply_exact_text`, `public_comment_reply_exact_text_variants`.

> **מפתח אחד לא מוכר דוחה את כל הבקשה.** `PUT /campaigns/{campaignId}` מאמת את כל גוף הבקשה מול רשימת מותרים. מפתח שאינו מזוהה מחזיר `400` עבור הבקשה כולה — הוא לא מתעלם בשקט, ואף אחד מהשדות האחרים באותו גוף לא נכתב.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

> התגובה הגלויה שנותרה על התגובה דורשת את תכונת תגובה-לתגובה בתוכנית שלך. בלעדיה, ההודעה הפרטית עדיין נשלחת והתגובה הציבורית מדלגת.

---

## אופטימיזציה של קמפיין באמצעות בינה מלאכותית

`POST /campaigns/{campaignId}/optimize`

מריץ את אותו שכתוב AI כמו בתהליכי ה-Optimize ומשוב ה-thumbs-down בלוח הבקרה: לוקח את המשוב שלך, משכתב את ההוראות של הבוט, ומכין את התוצאה כטיוטה חדשה לעיונך.

| שדה | נדרש | תיאור |
|---|---|---|
| `user_feedback` | אחד משני אלו נדרש | משוב חופשי המתאר מה לשפר. |
| `thumbs_down_feedback` | אחד משני אלו נדרש | משוב שנאסף מסימון thumbs-down על תשובה ספציפית של בוט. |
| `thumbs_down_message` | לא | הודעת הבוט שאליה מתייחס משוב ה-thumbs-down. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'
```

**תגובה** (`202` — השכתוב רץ ברקע)

```json
{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }
```

בצע סקר [`GET /campaigns/{campaignId}`](#get-a-campaign) ועקוב אחר `test_bot.status`: הוא משתנה ל-`"Optimizing"` מיד, ולאחר מכן חוזר ל-`"Draft"` ברגע שהשכתוב מגיע ל-`test_bot`. משם הוא מתנהג כמו כל טיוטה בלוח הבקרה — עיין בה, ולאחר מכן פרסם אותה בלוח הבקרה כדי להפוך אותה לפעילה. `409` פירושו שאופטימיזציה כבר רצה עבור קמפיין זה.

> אופטימיזציה צורכת קרדיטים, בדיוק כמו כל פעולת AI אחרת בחשבונך.

---

## שיוך איש קשר לקמפיין

`POST /campaigns/{campaignId}/contacts/{contactId}/assign`

מכניס איש קשר קיים לקמפיין, ואם תבקש זאת, שולח את הודעת הפתיחה של הקמפיין באופן מיידי. זו הדרך לשלוח תבנית WhatsApp מאושרת של קמפיין לאיש קשר אחד: התבנית שבאמצעותה אושר הקמפיין שייכת לאותו קמפיין, ולכן היא אינה מופיעה בספריית ה-[Templates API](templates.md) ולא ניתן לשלוח אותה דרך `/whatsapp-templates/send`.

| שדה | נדרש | תיאור |
|---|---|---|
| `sendOpeningMessage` | לא | `true` שולח את הודעת הפתיחה של הקמפיין (תבנית ה-WhatsApp המאושרת בקמפיין WhatsApp) ברגע שאיש הקשר משויך. ברירת המחדל היא `false`. |
| `triggerAIResponse` | לא | `true` מאפשר ל-AI לכתוב בעצמו את ההודעה הראשונה במקום זאת. ברירת המחדל היא `false`. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'
```

**תגובה**

```json
{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}
```

> **קרדיטים:** שליחת הודעת הפתיחה בקמפיין WhatsApp מחויבת כמו כל שליחת תבנית, ומתומחרת לפי מדינת הנמען וקטגוריית התבנית. בערוצים אחרים, הודעת הפתיחה היא הודעה יוצאת רגילה.

---

## ניתוב קמפיין לערוצים נכנסים

נקודות קצה אלו מנהלות איזה קמפיין עונה לאנשי קשר חדשים ולא מוכרים בערוץ. **העדף נקודות כניסה** (Entry Points) עבור אינטגרציות חדשות (ראה את ההערה תחת [סוגי קמפיינים](#campaign-types)) — אלו נשארות שימושיות לעבודה עם קמפיינים שמנותבים בדרך הישנה, ולפתרון התנגשות בעלות על ערוץ בין שני קמפיינים נכנסים.

### הקצאת קמפיין לערוצים נכנסים

`POST /campaigns/{campaignId}/incoming-routing`

| שדה | נדרש | תיאור |
|---|---|---|
| `channels` | כן | מערך של ערוצים שקמפיין זה אמור לענות עבורם לאנשי קשר חדשים ולא מוכרים. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'
```

**תגובה**

```json
{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}
```

`channels` מפרט רק את הערוצים שנותבו בפועל לקמפיין זה; `failed` מפרט את כל אלו שלא. אם כל ערוץ מבוקש נכשל, הבקשה עצמה נכשלת.

### ניקוי ניתוב נכנס של קמפיין

`DELETE /campaigns/{campaignId}/incoming-routing`

| שדה | נדרש | תיאור |
|---|---|---|
| `channelToUnassign` | לא | נקה ניתוב עבור ערוץ בודד זה בלבד. השמט כדי לנקות כל ערוץ שקמפיין זה עונה עבורו כרגע. |

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'
```

**תגובה**

```json
{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}
```

### הפעלה מחדש של קמפיין רדום

`POST /campaigns/{campaignId}/reactivate`

מחזיר קמפיין מ-`Ended`, `Completed`, `Paused` או `Draft` ותובע מחדש את הערוצים שלו. עובד רק על קמפיינים מסוג `Incoming from Unknown Contacts` או `Combined` — קמפיין שכבר נמצא ב-`Live` מטופל כהצלחה ללא צורך בפעולה נוספת.

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}
```

ערוץ שכבר נתבע על ידי סוכן של קמפיין אחר יופיע ב-`channelsBlockedByConflict` במקום לגרום לכשל של כל הקריאה — השתמש ב-[עצירת קמפיין נכנס מתנגש](#stop-a-conflicting-incoming-campaign) למטה כדי לשחרר אותו תחילה אם ברצונך שקמפיין זה ישתלט עליו. `400` מוחזר עבור סוג קמפיין שאינו תומך בהפעלה מחדש, או סטטוס שאינו אחד מהסטטוסים הרדומים לעיל.

### עצירת קמפיין נכנס מתנגש

`POST /campaigns/{campaignId}/stop-incoming`

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

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}
```

`released_channels` חוזר ריק כאשר קמפיין זה כבר מחזיק בכל ערוץ שהוא מפרסם — אין מה להשתלט עליו.

---

## הערכות עלות

הערך כמה יעלה להשיק קמפיין לפני שתשלח אותו.

### הערכת עלות תבנית WhatsApp

`GET /campaigns/{campaignId}/template-cost-estimate`

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}
```

`billing_mode` הוא `"credits"` בנתיב ה-WhatsApp המנוהל. בנתיב שבו Meta מחייבת את חשבון ה-WhatsApp Business שלך ישירות, `costPerContact`, `subtotal` ו-`totalTemplateCost` חוזרים כ-`null` — לעולם לא `0`, מה שהיה מתפרש כחינם — מכיוון שאין נתון אשראי לדווח עליו.

### הערכת עלות SMS

`GET /campaigns/{campaignId}/sms-cost-estimate`

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}
```

SMS נשלח תמיד דרך חשבון ה-Twilio שלך (ראה [ספק SMS](../settings/sms-provider.md)), לכן החיוב מתבצע תמיד על ידי Twilio ישירות — `estimatedCostUsd` הוא הערכה של חשבונית Twilio זו, לא חיוב אשראי.

---

## בדיקות מגבלה

בדוק מגבלה לפני ההשקה, במקום לגלות זאת משליחה שנכשלה.

### בדיקות ברמת הקמפיין

`GET /campaigns/{campaignId}/limits/ai-credit-messaging` — האם השקה או תזמון של קמפיין זה יחרגו ממגבלת הודעות ה-AI-credit של החשבון שלך.

`GET /campaigns/{campaignId}/limits/messaging` — האם זה יחרוג ממגבלת ההודעות היומית של החשבון שלך.

```bash
curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"
```

**תגובה** (המגבלה לא נחרגה)

```json
{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}
```

במקום זאת מוחזר `400` כאשר המגבלה נחרגת, עם הסיבה בתוך `error`.

### בדיקות ברמת החשבון

`GET /campaigns/limits/campaigns` — האם הגעת למגבלת יצירת הקמפיינים החודשית של המנוי שלך.

`GET /campaigns/limits/contacts` — האם הגעת למגבלת אנשי הקשר של המנוי שלך.

```bash
curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}
```

---

## סיכומי נתוני קמפיין

`GET /campaigns/stats/totals`

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

| פרמטר שאילתה | תיאור |
|---|---|
| `days` | גודל חלון הזמן המתגלגל, 1-365. ברירת המחדל היא 90. |

```bash
curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}
```

`byAgent` הוא סיכום עצמאי, לא סכום של `byCampaign` — תעבורה של חשבון מבוסס AI-Agent יכולה להתקיים ללא קמפיין כלל, ולכן אחרת היא הייתה בלתי נראית כאן.

---

## בדיקת קמפיין בסביבת הניסוי (Playground)

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

התהליך הוא: צור איש קשר בדיקה נסתר, שלח הודעה, ולאחר מכן תשאל את הקמפיין לגבי תשובת הבוט. תשובות נוצרות באופן אסינכרוני, לכן הן מגיעות ב-`test_messages` בקמפיין ולא בגוף התגובה.

> **ה-Playground פועל על חשבון קרדיט ה-API.** שיחת בדיקה שמתחילה עם מפתח API מחויבת בתעריף הרגיל של הודעת AI, בדיוק כמו תשובה אמיתית, ומופיעה בהיסטוריית השימוש שלך כרשומה רגילה. בדיקה מתוך לוח הבקרה נשארת בחינם. ההבדל הוא מכוון: הרצת בדיקה מבצעת את אותה עבודת AI כמו הרצה חיה, לכן Playground ללא הגבלה של API היה מאפשר להריץ AI ללא הגבלה על חשבון מישהו אחר.

### שלב 1 - יצירת איש קשר הבדיקה

`POST /campaigns/{campaignId}/try-out/contact`

יוצר את איש הקשר הנסתר לבדיקה ומקשר אותו לקמפיין. כל שדות הגוף הם אופציונליים; כל מה שתשמיט יחזור לזהות לדוגמה מובנית (John Doe).

| שדה | נדרש | תיאור |
|---|---|---|
| `first_name` | לא | השם הפרטי של איש הקשר לבדיקה. |
| `last_name` | לא | שם המשפחה של איש הקשר לבדיקה. |
| `email` | לא | כתובת האימייל של איש הקשר לבדיקה. |
| `phone` | לא | מספר הטלפון של איש הקשר לבדיקה. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'
```

**תגובה**

```json
{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}
```

### שלב 2 - רישום ההודעה הנכנסת

`POST /campaigns/{campaignId}/try-out/messages`

מוסיף הודעות לשרשור הבדיקה. שלח את הודעת המבקר לכאן תחילה, כדי שתופיע בהיסטוריית השיחה שהבוט קורא.

| שדה | נדרש | תיאור |
|---|---|---|
| `messages` | כן | מערך של אובייקטי הודעה, מקסימום 200 לבקשה. |
| `messages[].body` | כן | טקסט ההודעה. |
| `messages[].direction` | כן | `"inbound"` עבור המבקר, `"outbound"` עבור הבוט. |
| `messages[].timestamp` | לא | מחרוזת ISO-8601 או מילי-שניות מאז תקופת Unix. |
| `messages[].role` | לא | תווית תפקיד אופציונלית. |
| `messages[].name` | לא | שם תצוגה אופציונלי. |
| `ignoreCounter` | לא | מספר שלם. מאפס את מונה ההתעלמות של הקמפיין באותה כתיבה. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}
```

### שלב 3 - בקש מהבוט להשיב

`POST /campaigns/{campaignId}/try-out/test-message`

שולח את ההודעה לצינור ה-AI. זו הקריאה שמייצרת בפועל תגובת בוט.

| שדה | נדרש | תיאור |
|---|---|---|
| `message` | כן | טקסט ההודעה האחרונה של המבקר. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'
```

**תגובה**

```json
{
  "success": true,
  "data": "Published"
}
```

`"Published"` פירושו שההודעה עברה לצינור ה-AI. `"Ignored"` פירושו שהודעת בדיקה חדשה יותר החליפה את זו — אזור הבדיקה מאחד רצף מהיר של הודעות לתגובה אחת, בערך ארבע שניות לאחר ההודעה האחרונה, באותו אופן שבו שיחה אמיתית ממתינה למישהו שיסיים להקליד. בגלל חלון איחוד זה, קריאה זו לוקחת כמה שניות עד להחזרת תשובה.

### שלב 4 - קריאת התשובה

`GET /campaigns/{campaignId}`

תשובת הבוט מתווספת למערך ה-`test_messages` של הקמפיין. בצע סקר (Poll) על הקמפיין עד שיופיע ערך `outbound` חדש.

```json
{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}
```

### איפוס אזור הבדיקה

`POST /campaigns/{campaignId}/try-out/reset`

מנקה את כל ארגז החול: מוחק את איש הקשר לבדיקה, מוחק את `test_messages`, ומשחרר את נעילות התגובה של הבוט. השתמש בזה בין הרצות בדיקה.

```bash
curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"
```

**תגובה**

```json
{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```

### נקודות קצה אחרות של אזור המשחקים (playground)

| נקודת קצה | מה היא עושה |
|---|---|
| `DELETE /campaigns/{campaignId}/try-out/contact` | מוחקת רק את איש הקשר הנוכחי לבדיקה ומבטלת את הקישור שלו, תוך השארת `test_messages` ללא שינוי. מצליחה גם כאשר לא מקושר איש קשר. |
| `POST /campaigns/{campaignId}/try-out/transfer` | מתחילה אזור משחקים חדש עם שיחה קיימת, בבקשה אחת: מחליפה את איש הקשר לבדיקה ודורסת את `test_messages`. הגוף מקבל את `first_name`, `last_name`, `messages` (יכול להיות ריק) ו-`ignoreCounter`. העדף זאת על פני מחיקה-ואז-יצירה-ואז-הוספה, שמשלשת את ניצול מכסת הקצב שלך. |
| `POST /campaigns/{campaignId}/try-out/messages/replace` | דורסת את `test_messages` במלואו במקום להוסיף עליו. השתמש בזה כדי לקטוע או להריץ אחורה שרשור. |
| `POST /campaigns/{campaignId}/try-out/contact/reset-ignore-counter` | מאפסת רק את מונה ההתעלמות של איש הקשר לבדיקה, עבור תהליכי ביצוע חוזר וחזרה לאחר שליחה. |

---

## שגיאות API של קמפיינים

נקודות קצה של קמפיינים מחזירות את מעטפת השגיאה הסטנדרטית:

```json
{
  "success": false,
  "error": "Campaign not found"
}
```

| סטטוס | מתי זה קורה בנקודת קצה של קמפיין |
|---|---|
| `400` | שדה חובה חסר או לא תקין (לדוגמה `type` שגוי, `enabled` שאינו בוליאני, או מפתח יום בשבוע לא מוכר). מוחזר גם על ידי נקודת קצה של [בדיקת מגבלה](#limit-checks) כאשר המגבלה עומדת להיחרג, ועל ידי [הפעלה מחדש](#reactivate-a-dormant-campaign) עבור סוג קמפיין או סטטוס שאינם תומכים בכך. |
| `404` | הקמפיין לא נמצא — או שהוא לא קיים או שהוא שייך לחשבון אחר. |
| `409` | [אופטימיזציה](#optimize-a-campaign-with-ai) כבר רצה עבור קמפיין זה. |

הקודים המשותפים שכל נקודת קצה יכולה להחזיר — `401`, `403` (התוכנית שלך אינה כוללת גישת API), `429` (מגבלת קצב) ו-`500` — מפורטים עם הנחיות לניסיון חוזר ב-[שגיאות ועימוד](errors-and-pagination.md).

---

## קשור

- [ניתוב ערוץ לקמפיין](channels.md#route-a-channel-to-a-campaign) — הפנו את Instagram, WhatsApp או כל ערוץ אחר לסוכן ה-AI שאמור להשיב לו, באמצעות נקודות כניסה (Entry Points).
- [יצירת תבניות המשך עם AI](templates.md#generate-follow-up-templates-with-ai) — הפעילו משימת רקע שכותבת את תבניות ההמשך ב-WhatsApp עבור קמפיין.
- [API של שאלות ותשובות (FAQs)](faqs.md) — נהלו את רשומות השאלות והתשובות שבהן משתמשים הקמפיינים שלכם.
- [גישת API](../integrations/api-access.md) — צרו את מפתח ה-API שלכם.
- [אימות](authentication.md) — כל הדרכים להעברת המפתח שלכם.