Campaigns API #

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

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

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

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

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

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

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

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

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

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

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

GET /campaigns

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

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

cURL

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

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

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"])

תגובה

{
  "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

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

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

import requests

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

תגובה

{
  "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
    }
  }
}

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

POST /campaigns

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

שדות הבקשה

cURL

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

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

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"]

תגובה

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

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

PUT /campaigns/{campaignId}

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

אילו שדות ניתן לשנות. כל מה שעורך הקמפיין כותב, כולל 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 ניתנים כולם לעריכה בדרך זו, וכך גם כל הגדרת בוט אחרת המפורטת תחת שדות הגדרת בוט. אותו דבר חל על test_bot, frequency, ו-follow_up_config.

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

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

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

cURL

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

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

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()

תגובה

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

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

DELETE /campaigns/{campaignId}

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

cURL

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

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

import requests

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

תגובה

{
  "success": true
}

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

POST /campaigns/{campaignId}/duplicate

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

cURL

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

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

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"]

תגובה

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

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

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

PATCH /campaigns/{campaignId}/enabled

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

שדות הבקשה

cURL

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

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

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()

תגובה

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

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

PATCH /campaigns/{campaignId}/archived

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

שדות הבקשה

cURL

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

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

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()

תגובה

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

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

PUT /campaigns/{campaignId}/bot-config

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

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

cURL

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

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

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()

תגובה

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

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

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

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

PUT /campaigns/{campaignId}/active-hours

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

שדות הבקשה

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

cURL

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

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

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()

תגובה

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

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

GET /campaigns/{campaignId}/custom-functions

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

cURL

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

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

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"]

תגובה

{
  "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

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

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" }'

תגובה

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

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

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

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

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

תגובה

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

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

POST /campaigns/{campaignId}/kb-sources

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

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" }'

תגובה

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

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

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

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

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

תגובה

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

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

POST /campaigns/{campaignId}/mcp-servers

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

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" }'

תגובה

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

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

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

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

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

תגובה

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

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

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

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

GET /campaigns/{campaignId}/media-library

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

תגובה

{
  "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

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."
  }'

תגובה

{
  "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}

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

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" }'

תגובה

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

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

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

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

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

תגובה

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

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

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

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

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

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

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

cURL

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

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

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()

תגובה

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

קרא את התגיות בחזרה עם GET /campaigns/{campaignId}.

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

POST /campaigns/{campaignId}/tags

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

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} של המערך כולו לעיל.

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} כאשר ייתכן שגורם אחר עורך את הקמפיין באותו הזמן.

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

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

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

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

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" }'

תגובה

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

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

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

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

חבר תחילה את דף הפייסבוק — ראה חיבור ערוץ. לאחר מכן הגדר את השדות להלן באמצעות PUT /campaigns/{campaignId}.

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

שדות

ניקוי שדה

שדות אלו מוסרים במקום להיות מוגדרים כ-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

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

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

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()

תגובה

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

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

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

POST /campaigns/{campaignId}/optimize

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

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 — השכתוב רץ ברקע)

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

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

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

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

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

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

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 }'

תגובה

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

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

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

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

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

POST /campaigns/{campaignId}/incoming-routing

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"] }'

תגובה

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

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

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

DELETE /campaigns/{campaignId}/incoming-routing

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

תגובה

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

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

POST /campaigns/{campaignId}/reactivate

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

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

תגובה

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

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

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

POST /campaigns/{campaignId}/stop-incoming

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

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

תגובה

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

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

הערכות עלות #

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

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

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

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

תגובה

{
  "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

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

תגובה

{
  "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), לכן החיוב מתבצע תמיד על ידי Twilio ישירות — estimatedCostUsd הוא הערכה של חשבונית Twilio זו, לא חיוב אשראי.

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

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

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

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

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

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

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

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

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

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

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

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

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

תגובה

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

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

GET /campaigns/stats/totals

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

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

תגובה

{
  "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).

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" }'

תגובה

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

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

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

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

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"
      }
    ]
  }'

תגובה

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

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

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

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

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?" }'

תגובה

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

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

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

GET /campaigns/{campaignId}

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

{
  "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, ומשחרר את נעילות התגובה של הבוט. השתמש בזה בין הרצות בדיקה.

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

תגובה

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

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

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

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

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

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

קשור #

• ניתוב ערוץ לקמפיין — הפנו את Instagram, WhatsApp או כל ערוץ אחר לסוכן ה-AI שאמור להשיב לו, באמצעות נקודות כניסה (Entry Points).
• יצירת תבניות המשך עם AI — הפעילו משימת רקע שכותבת את תבניות ההמשך ב-WhatsApp עבור קמפיין.
• API של שאלות ותשובות (FAQs) — נהלו את רשומות השאלות והתשובות שבהן משתמשים הקמפיינים שלכם.
• גישת API — צרו את מפתח ה-API שלכם.
• אימות — כל הדרכים להעברת המפתח שלכם.