API של סוכני AI #

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

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

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

אם המושג “סוכנים” חדש לך, קרא תחילה את סוכני AI.

כיצד סוכן מורכב #

ארבעה דברים מנוהלים בנפרד, וכדאי לדעת מהו מה לפני שמתחילים:

סוכן חדש לא עונה לאף אחד עד שתנתב אליו. יצירת סוכן לא מציבה אותו בערוץ כלשהו. זהו הצעד שרוב האינטגרציות מפספסות — ראה ניתוב שיחות לסוכן בסוף דף זה.

אובייקט הסוכן #

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

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

המסמך המלא מוסיף את כל השאר: instructions, rules, personality, availability, follow_up_config, רשימות ה-FAQ ומקורות הידע המקושרים, בלוקים של טקסט שנוצרו, וכל מצב ריצה (tag_generation, optimize_run).

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

רשימת סוכנים #

GET /agents — כל סוכן בחשבון, מהחדש ביותר לישן ביותר.

נקודת קצה זו אינה מרובת דפים (paged). כברירת מחדל, כל סוכן (Agent) מוחזר עם התצורה המלאה שלו, שהיא כבדה: סוכן בודד יכול להגיע ל-580 KB וחשבון עם 64 סוכנים ליותר מ-3 MB. העבירו view=summary עבור שורה קצרה לכל סוכן, ולאחר מכן קראו את הסוכן הרצוי באמצעות קבלת סוכן.

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

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

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

Python

import requests

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

תגובה (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

יצירת סוכן #

POST /agents — רק name נדרש באמת; שלחו כל תצורה שאתם כבר מכירים לצדו. סוכן חדש פעיל כברירת מחדל.

שדות בקשה (כולם אופציונליים למעט name)

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

תגובה (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued הוא true כאשר הפלטפורמה החלה לכתוב את ההוראות מהדפים שסיפקתם.

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

קבלת סוכן #

GET /agents/{agentId}

העבירו fields עם רשימה מופרדת בפסיקים כדי לקבל בחזרה רק את מה שאתם צריכים, לדוגמה fields=name,active,goal. ה-id תמיד נכלל, ושמות שאינם קיימים בסוכן יתעלמו במקום להידחות. השמיטו אותו כדי לקבל את המסמך המלא.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

סוכן שאינו קיים בחשבונכם יחזיר 404.

עדכון סוכן #

PUT /agents/{agentId} — שלחו רק את השדות שברצונכם לשנות; כל השאר יישאר ללא שינוי.

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

הערות

• כדי לשנות את סוג האירוע הניתן להזמנה שאליו הסוכן מזמין, שלח את event_id (מזהה האירוע, או null כדי לנקות אותו). שלח את event_ids עם מערך כדי לקשר כמה בבת אחת — הראשון הופך לראשי ו-[] מבטל את הקישור של הכל. event_id ו-event_ids מוציאים זה את זה, ולא ניתן לכתוב ישירות לשדה event עצמו.
• enable_bookings חייב להיות בוליאני אמיתי, ו-booking_provider חייב להיות אחד מ-default, zenchef, formitable.
• שדות בעלות וזהות מתעלמים, וכך גם מצב הריצה הפנימי (התקדמות יצירה ואופטימיזציה).
• ניתוב לא מוגדר כאן. השתמש ב-PUT /entry-points/channel-defaults כדי להפוך את הסוכן למשיב עבור ערוץ, ב-POST /agents/{agentId}/entry-points עבור כללי מילות מפתח ותגובות, וב-PATCH /agents/{agentId}/active כדי להשהות או להמשיך אותו.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  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" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

גוף ריק מחזיר 400 עם "No fields to update".

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

PUT /agents/{agentId}/bot-config — הדרך הממוקדת לשינוי הגדרות השיחה בלבד.

לסוכן אין מקטע בוט נפרד: ההגדרות שלו יושבות ישירות על הסוכן, לכן שמות השדות כאן זהים לאלו שהיית שולח ל-PUT /agents/{agentId}. נקודת קצה זו קיימת כדרך בטוחה וממוקדת לשינוי חלק מהם. נדרש לפחות שדה אחד.

שמות שדות חייבים להיות שמות פשוטים כאן — אותיות, מספרים, קווים תחתונים ומקפים. נתיבים עם נקודות אינם מתקבלים בנקודת קצה זו (בניגוד ל-PUT /agents/{agentId}), לכן bot.goal נדחה עם 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

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

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

PUT /agents/{agentId}/active-hours — השעות שבהן הסוכן משיב באופן אוטומטי. מחוץ לחלונות אלו הוא נשאר שקט.

שלח אובייקט availability עם מפתח לפי יום בשבוע (monday עד sunday). כל יום מקבל חלון זמן בודד או רשימת חלונות, בפורמט HH:MM של 24 שעות. ימים שתשמיט ישמרו על מה שהיה להם, וכל מפתח שאינו יום בשבוע יידחה — כך ששגיאת הקלדה לא יכולה לגרום לחוסר פעולה שקט.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/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" }
      ]
    }
  }'

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

מפתח יום בשבוע שגוי מחזיר 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

השהיה או חידוש של סוכן #

PATCH /agents/{agentId}/active — מפעיל או מכבה את הסוכן. סוכן מושהה שומר על כל הגדרותיו אך מפסיק להשיב באופן מיידי; החזרה לפעילות נכנסת לתוקף מיד.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active חייב להיות ערך בוליאני אמיתי — כל ערך אחר יחזיר 400 עם "active (boolean) is required".

שכפול סוכן #

POST /agents/{agentId}/duplicate — יוצר עותק עם הגדרותיו השמורות. העותק לא שולח דבר עד שתפנה אליו ערוץ או נקודת כניסה (Entry Point).

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

תגובה (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

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

מחיקת סוכן #

DELETE /agents/{agentId}

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

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

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

חסום (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

טיוטות: סקירת שינויים לפני שהם הופכים לפעילים #

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

פרסום הטיוטה #

POST /agents/{agentId}/publish-draft — מעביר את הטיוטה להגדרות הפעילות ומנקה את הטיוטה באותו שלב.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

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

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

בטל את הטיוטה #

POST /agents/{agentId}/discard-draft — זורק את הטיוטה ומשאיר את התצורה הפעילה בדיוק כפי שהיא. בטוח לקריאה כאשר אין טיוטה; שום דבר לא קורה.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

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

POST /agents/{agentId}/optimize — משכתב את תצורת הסוכן על סמך המשוב שלך (“הוא ממשיך להציע הנחות”, “התשובות ארוכות מדי”) ושומר את השכתוב כטיוטה במקום להפעיל אותו בשידור חי.

שלח user_feedback (הוראה פשוטה) או, בעת תגובה לתשובה שגויה ספציפית, thumbs_down_feedback יחד עם ה-thumbs_down_message הפוגעני. לפחות אחד מהשניים חייב להכיל טקסט.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

תגובה (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

העבודה רצה ברקע והקריאה חוזרת מיד. קרא את הסוכן עם GET /agents/{agentId} ועקוב אחר optimize_run.status; ברגע שהוא חוזר ל-Draft, השכתוב ממתין כטיוטה של הסוכן. עיין בו, ולאחר מכן פרסם אותו או בטל אותו.

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

כללי תיוג #

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

אובייקט הכלל

הוסף כלל תיוג #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

החלף כלל תיוג #

PUT /agents/{agentId}/tags/{tagId} — הכלל נמצא לפי מזהה התגית בנתיב ומוחלף במלואו, לא ממוזג, לכן שלח את הכלל המלא במקום רק את החלק שאתה משנה. התגית שאליה הוא מצביע נשמרת גם אם תשאיר את tag_id בחוץ, כך שעריכה לא יכולה לנתק את הכלל מהתגית שלו.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

הסרת כלל תיוג #

DELETE /agents/{agentId}/tags/{tagId} — הסוכן מפסיק להחיל את התגית הזו. התגית עצמה, וכל אנשי הקשר שכבר נושאים אותה, נשארים ללא שינוי.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

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

יצירת קבוצת תגיות באמצעות בינה מלאכותית #

POST /agents/{agentId}/tags/generate — מתכנן סט שלם של כללים (שמות התגיות והניסוח “החל כאשר…” מאחורי כל אחד מהם) על ידי קריאת ההוראות והמטרה של הסוכן עצמו.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

תגובה (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

העבודה רצה ברקע. קרא את ה-Agent וצפה ב-tag_generation.status; הכללים עצמם מגיעים ל-tags של ה-Agent. הרצה אחת בלבד בכל פעם לכל Agent (אחרת 409), והיא משתמשת בנקודות AI.

מקורות ידע #

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

מאיפה מגיעים מזהי המקור (source ids). הוסף תוכן באמצעות נקודות הקצה של בסיס הידע — POST /kb-sources/url עבור דף, POST /kb-sources/file עבור מסמך, POST /kb-sources/bulk-import עבור אתר שלם. אלו מחזירים source_id שעליו יש לבצע סקר (poll) עם GET /kb-sources/{sourceId} עד שהוא מוכן. POST /kb-sources/url מקבל גם autoLinkToAgentId, שמצרף את המקור ל-Agent ברגע שהייבוא מסתיים, כך שניתן לדלג על קריאת הצירוף בהמשך.

צירוף מקורות ידע #

POST /agents/{agentId}/kb-sources — שלח kb_source_ids עם רשימה כדי לצרף קבוצה שלמה בקריאה אחת (מה שתרצה לאחר סריקת אתר), או kb_source_id עבור מקור בודד. שלח את האחד או את האחר. צירוף של משהו שכבר מצורף לא משנה דבר.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

תגובה (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

ניתוק מקורות ידע #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} עבור אחד, או POST /agents/{agentId}/kb-sources/bulk-remove עם kb_source_ids עבור כמה. הסרה מרוכזת היא POST מכיוון שרשימת המזהים עוברת בגוף הבקשה.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

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

שאלות נפוצות (FAQs) #

שאלות נפוצות מנוהלות בנקודות קצה משלהן ומקושרות לסוכן משם: POST /faqs/{faqId}/link עם { "agent_id": "ag7HkQ2ZpLxR3mNb" }, ו-POST /faqs/{faqId}/unlink כדי להסיר את הקישור שוב. ניתן לשתף שאלה נפוצה בין כל מספר של סוכנים. עיין ב-API של שאלות נפוצות.

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

כלים #

פונקציות מותאמות אישית #

POST /agents/{agentId}/custom-functions מאפשר לסוכן לקרוא לאחת מהפונקציות המותאמות אישית שלך במהלך שיחות. ניתן לחבר רק פונקציות השייכות לאותו חשבון, וחיבור של פונקציה שכבר מחוברת אינו משנה דבר.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} מנתק אותה. הפונקציה עצמה אינה נמחקת ונשארת זמינה עבור הסוכנים האחרים שלך.

נהל את הפונקציות עצמן ב-/custom-functions — עיין ב-פונקציות מותאמות אישית כדי להבין מהן.

שרתי MCP #

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

שרתי MCP דורשים את תכונת הפונקציות המותאמות אישית בתוכנית שלך. ללא תכונה זו, נקודות הקצה ברמת החשבון /mcp-servers יחזירו 403. חיבור שרת שכבר רשום לסוכן אינו מוגבל.

רישום שרת #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

תגובה (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

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

auth_type של oauth2 שומר את הרישום עם oauth_connected: false וללא כלים: עדיין אין אסימון (token). אישור שרת OAuth דורש התחברות דרך דפדפן ומתבצע מלוח הבקרה, לא דרך ה-API.

הצגה, עדכון ומחיקה של שרתים #

• GET /mcp-servers — כל שרת רשום, מהחדש לישן, תחת servers.
• PUT /mcp-servers/{serverId} — שלח רק את מה שברצונך לשנות. שינוי ה-URL או שדות האימות בודק מחדש את החיבור ומרענן את רשימת הכלים השמורה במטמון.
• DELETE /mcp-servers/{serverId} — מסיר את הרישום ומנתק אותו מכל סוכן וקמפיין שהיה מופעל עבורם.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

סודות לעולם לא חוזרים. תגובות נושאות auth_header_value_set (דגל true/false המציין שערך כלשהו מאוחסן) במקום פרטי האימות, ואסימוני OAuth וסודות לקוח נשארים בצד השרת. כל השאר מוחזר: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

בדיקת חיבור #

POST /mcp-servers/test-connection — מתחבר לשרת ומציג את הכלים שלו. שתי דרכים להפעיל אותו:

• עם server_id — בודק את התצורה השמורה ומרענן את רשימת הכלים השמורה במטמון;
• עם url מוטבע (בתוספת auth_header_name / auth_header_value) — בדיקה לפני שמירה שאינה שומרת דבר.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

תגובה (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

כשל בחיבור הוא לא שגיאת HTTP — אתה מקבל 200 עם success: false ו-error שמתאר מה השתבש, כך שתוכל להציג זאת לצד השדה שהמפעיל עורך.

צירוף שרת לסוכן #

רישום שרת אינו מעניק לאף סוכן גישה אליו. צרף אותו:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

תגובה (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} מנתק אותו שוב. השרת עצמו אינו נמחק ונשאר זמין לסוכנים האחרים שלך. צירוף או ניתוק של פריט שכבר נמצא במצב זה לא משנה דבר.

ספריית מדיה #

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

הצגת מדיה #

GET /agents/{agentId}/media-library

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

תגובה (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

פריטים המאוחסנים ב-Agent מופיעים ראשונים, ולאחריהם פריטים ישנים יותר שעדיין מאוחסנים בקמפיין שממנו נבנה ה-Agent; media_home (agent או campaign) מציין מהו מה. בתוך כל קבוצה, החדש ביותר מופיע ראשון.

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

העלאת מדיה #

POST /agents/{agentId}/media-library — הקובץ מועלה בתוך גוף הבקשה כ-base64, עד 10 MB. הקריאה חוזרת ברגע שהקובץ מאוחסן, לכן יש להמתין מעט יותר מאשר בבקשה רגילה. שימו לב שגוף זה משתמש בשמות שדות ב-camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

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

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

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

PATCH /agents/{agentId}/media-library/{itemId} — מטא-נתונים בלבד. לא ניתן להחליף את הקובץ עצמו; יש להעלות פריט חדש ולמחוק את הישן. גוף זה משתמש ב-snake_case: title, description, send_message, max_sends_per_conversation (מספר שלם אי-שלילי, או null כדי לנקות את המגבלה).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

תגובה (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

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

DELETE /agents/{agentId}/media-library/{itemId} — מסיר את הפריט ואת הקובץ המאוחסן שלו. מחיקת פריט שכבר אינו קיים מצליחה ומדווחת על deleted: false, כך שניתן לנסות את הקריאה שוב בבטחה.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

יצירת הודעות המשך #

POST /agents/{agentId}/template-generation — כותב עבורך את הודעות ההמשך של ה-Agent (התזכורות שהוא שולח כאשר שיחה הופכת לשקטה), בהתבסס על המטרה שלשמה נועד ה-Agent.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

ישנן שתי דרכים שבהן זה חוזר, והשדה target מציין איזו מהן:

• target: "agent" עם 200 — ההודעות נכתבו במהלך השיחה והתוצאה נמצאת ב-data. קרא אותן בחזרה מתוך ה-follow_up_config של הסוכן. זהו המקרה הרגיל.
• target: "campaign" עם 202 — העבודה הוכנסה לתור מול הקמפיין ששמו מופיע ב-campaign_id. עקוב אחר ה-template_generation_status של אותו קמפיין עד לסיומו.

cold_only זקוק לקמפיין יוצא ונדחה עם 409 (reason: "cold_only_requires_campaign") עבור סוכן שאין לו כזה. 403 פירושו שמעקבים אוטומטיים אינם מופעלים עבור החשבון. פעולה זו משתמשת בקרדיטים של בינה מלאכותית, ו-400 עם "Insufficient credits." פירושו שנגמרו הקרדיטים בחשבון.

ניתוב שיחות לסוכן #

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

הצגת נקודות הכניסה של סוכן #

GET /agents/{agentId}/entry-points — חוקי הניתוב השולחים שיחות לסוכן זה, מהחדש לישן. מוחזרים גם חוקים נוכחיים וגם חוקים שהוצאו משימוש; חוק שהוצא משימוש כולל enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

עבור ברירות המחדל של הערוצים עבור כל החשבון, כולל ערוץ שהוגדר במכוון כך שלא יופנה לאף אחד, יש לקרוא את GET /entry-points/channel-defaults במקום זאת.

יצירת נקודת כניסה #

POST /agents/{agentId}/entry-points — הסוכן בנתיב תמיד מנצח, לכן לעולם לא ניתן ליצור חוק עבור סוכן שונה מזה המופיע ב-URL.

channels הוא שדה חובה ומציין אילו ערוצים החוק מכסה — לדוגמה whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget או custom_channel. חוקים חדשים מופעלים אלא אם צוין אחרת.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

תגובה (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

איזה חוק מנצח כאשר קיימים מספר חוקים רלוונטיים: שיחה מתמשכת או הקצאה ידנית שומרות על הסוכן שכבר הוקצה להן; אחרת, חוקי מילות מפתח גוברים על חוקי תגובות, שגוברים על חוקי עוקבים, וברירת מחדל של ערוץ היא מוצא אחרון. האם חוקים אלו קובעים משהו בחשבון מדווח על ידי GET /entry-points/routing-status.

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

שגיאות ב-API של סוכני AI #

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

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

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

הערה על ה-explorer. נקודות הקצה של /agents נמצאות במפרט ה-OpenAPI שפורסם, כך שתוכל לעיין בשדות המדויקים שלהן ולהריץ בקשות חיות ב-API Reference. נקודות הקצה ברמת החשבון של /mcp-servers נמצאות גם הן במפרט, כך שתוכל לחקור גם אותן שם.

קשור #

• סוכני AI — מהו סוכן, בשפה פשוטה.
• נקודות כניסה — כיצד שיחות מנותבות לסוכן.
• API של שאלות נפוצות — בנה וקשר את הידע שממנו הסוכן שלך עונה.
• API של ערוצים — חבר את הערוצים שבהם הסוכן עונה.
• חיבור שרתי MCP לבוט שלך · פונקציות מותאמות אישית
• API Reference — סייר נקודות הקצה האינטראקטיבי המלא.