API נקודות כניסה (Entry Points) #

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

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

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

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

הקריאה האחת שרוב האינטגרציות צריכות #

חבר ערוץ, צור סוכן, ואז כוון את הערוץ אל הסוכן:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

זוהי כל ההגדרה עבור “הסוכן הזה עונה ב-WhatsApp”. כל השאר בדף זה מיועד לכללים ספציפיים יותר (מילות מפתח, תגובות, עוקבים חדשים), מספרים מרובים בערוץ אחד, וקריאת ההגדרות הקיימות.

כיצד נקבע הניתוב #

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

1. אדם השתלט על השיחה — ללא בינה מלאכותית.
2. איש הקשר כבר משויך לסוכן, באופן ידני או מכיוון ששיחה עם אותו סוכן כבר מתנהלת — אותו סוכן ממשיך לטפל בה. נקודות כניסה לעולם לא מעבירות שיחה קיימת; כדי להעביר צ’אט לסוכן אחר, שייך אותו (באפליקציה, או באמצעות פעולת אוטומציות).
3. איש הקשר משיב לשידור (Broadcast) — הסוכן של השידור עונה, או אף אחד אם לשידור לא היה סוכן.
4. נקודת כניסה ספציפית תואמת. כללי מילות מפתח גוברים על כללי תגובות, שגוברים על כללי עוקבים. בין שני כללים מאותו סוג, האחרון שעודכן הוא המנצח.
5. ברירת המחדל של הערוץ שדרכו הגיעה ההודעה. ברירת מחדל המוגדרת למספר הספציפי שאליו כתב איש הקשר גוברת על ברירת המחדל של כל הערוץ.
6. שום דבר לא תאם — ההודעה מגיעה לתיבת הנכנסים של הצוות שלך ואף עוזר לא משיב.

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

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

אובייקט נקודת הכניסה #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

סוגי כללים #

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

הפניית ערוץ לנציג #

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

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

תגובה

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id הוא הכלל שנכנס כעת לתוקף; disabled_entry_point_ids מפרט את כל הכללים שהוסרו כדי לפנות לו מקום (ריק כאשר לא היה מה להחליף). רק אנשי קשר שמעולם לא שוחחת איתם מושפעים — כל מי שכבר נמצא בשיחה עם נציג שומר על אותו נציג.

400 פירושו ש-channel או agent_id חסרים, הנציג שייך לחשבון אחר, או ש-phone_number אינו אחד מהמספרים המחוברים שלך.

לראות מי משיב לכל ערוץ #

GET /entry-points/channel-defaults — ברירת המחדל של כל ערוץ בחשבון, מהחדש לישן, כולל ערוצים שהוצאו משימוש (enabled: false) וערוץ שהוגדר במכוון למצב “אף אחד” (agent_id: ""). סנן לפי enabled בעצמך כדי לקבל את התמונה העדכנית.

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

זוהי קריאה ברמת החשבון. הצגת הכללים של סוכן (Agent) אחד עם GET /agents/{agentId}/entry-points לא יכולה להציג ערוץ שהוגדר למצב “אף אחד”, מכיוון שכלל זה אינו שייך לאף סוכן.

עזיבת ערוץ שבו אף אחד לא עונה #

DELETE /entry-points/channel-defaults?channel=instagram — מסיר את ברירת המחדל של כל הערוץ עבור ערוץ אחד. שם הערוץ מצוין כפרמטר שאילתה, לא בגוף הבקשה. הוסף &phone_number=%2B31685101091 כדי לנקות רק את ברירת המחדל של אותו מספר ולאפשר למספר לחזור למי שעונה לערוץ.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { 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/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

ניתן לחזור על הפעולה בבטחה: ניקוי ערוץ שאין לו ברירת מחדל הוא 200 עם רשימה ריקה. ניקוי פירושו ביטול הגדרה, לא השתקה — בחשבון עם סוכן פעיל אחד בלבד, ערוץ שלא הוגדר עדיין יחזור לאותו סוכן. כדי להשאיר את ה-AI מחוץ לערוץ לחלוטין, בחר אף אחד לא עונה עבורו בלוח מי עונה לשיחות חדשות באפליקציה (פעולה זו כותבת ברירת מחדל מפורשת של “אף אחד” שברירת המחדל של המערכת לעולם לא תדרוס), או השהה את הסוכן עם PATCH /agents/{agentId}/active.

סוכן אחד לכל מספר WhatsApp #

ניתוב מתבצע כברירת מחדל לפי ערוץ: כל מספרי ה-WhatsApp שלך חולקים משיב אחד. עם שני מספרים או יותר המחוברים ב-WhatsApp Business או ב-WhatsApp Web, ניתן להגדיר ברירת מחדל למספר בודד, כך שעסק עם מספר לכל סניף או מותג יכול להקצות לכל אחד סוכן משלו בתוך חשבון אחד.

שלח phone_number עם קריאת ה-set:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• המספר חייב להיות אחד מהמספרים המחוברים שלך בערוץ זה, כפי שהוא מופיע תחת מספרים מחוברים (E.164 עם ה-+); כל דבר אחר הוא 400.
• הכלל נשמר כברירת מחדל של הערוץ עם match_config.phone_numbers: ["+31685101091"]. הודעה שמגיעה למספר זה מועברת לסוכן שלו; כל מספר אחר ממשיך לעקוב אחר ברירת המחדל של הערוץ כולו.
• הגדרה או הסרה של ברירת המחדל של הערוץ אינה משפיעה על כללים ברמת המספר, ולהיפך. הסר כלל ספציפי למספר עם DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• תשובות תמיד נשלחות מהמספר שאליו איש הקשר כתב, כך שאיש הקשר ממשיך לדבר עם אותו מספר ואותו סוכן.

הוספת כלל מצומצם יותר #

POST /agents/{agentId}/entry-points — יוצר כלל מילת מפתח, תגובה או עוקב (או ברירת מחדל לערוץ, אם כי PUT /entry-points/channel-defaults היא הבחירה הטובה יותר לכך מכיוון שהיא מסירה עבורך את המשיב הקודם). הסוכן בנתיב תמיד קובע: לא ניתן ליצור כלל עבור סוכן שונה מזה שמופיע ב-URL.

cURL

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

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

תגובה (201)

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

כלל תגובה להודעה פרטית (DM) שמגיב רק לתגובות הכוללות את המילה “LINK” בשני פוסטים ספציפיים, ממתין שתי דקות ושולח הודעה ראשונה קבועה:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

השאר את keywords ריק כדי לשלוח הודעה פרטית לכל מי שמגיב על הפוסטים הנעקבים, ואת post_ids ריק כדי לעקוב אחר כל פוסט. 400 מציין מה לא תקין: type לא ידוע, channels ריק, כלל מילת מפתח ללא מילות מפתח, או כלל תגובה שלא מציין את הערוץ שלו.

הצגת הכללים של סוכן #

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

cURL

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

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

שינוי כלל #

PUT /entry-points/{entryPointId} — משנה כלל אחד. שלח רק את השדות שאתה משנה; ניתן לגשת להגדרות מקוננות ברמת העלה עם מפתח מנוקד כגון "match_config.keywords". בכל פעם שהשינוי נוגע ב-type, channels או match_config, הכלל כולו נבדק מחדש, כך שעריכה חלקית לעולם לא תשאיר כלל לא שמיש (החלפת type ב-keyword ללא אספקת מילות מפתח תידחה). שליחת agent_id מעבירה את הכלל לסוכן אחר שלך; ערך ריק יידחה. שדות בעלות וזהות מתעלמים מהם.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

תגובה

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

עריכות נפוצות אחרות: { "enabled": false } מסיר כלל מבלי למחוק אותו, ו-{ "agent_id": "agOtherAgent" } מעביר אותו לסוכן אחר. גוף ריק מחזיר 400 עם "No fields to update".

מחיקת כלל #

DELETE /entry-points/{entryPointId} — מסיר את הכלל לצמיתות. שום דבר אחר לא מפנה לנקודת כניסה (Entry Point), לכן אין מה לנתק קודם.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  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/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

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

כדי להפסיק את הפעלת הכלל אך לשמור אותו, הגדר את enabled ל-false במקום זאת. ברירות מחדל של ערוץ בדרך כלל מוסרות (retired) ולא נמחקות, וזה מה ש-DELETE /entry-points/channel-defaults עושה.

בדיקה שהניתוב פעיל #

GET /entry-points/routing-status — מחזיר האם סולם נקודות הכניסה (Entry Points) קובע מי עונה בחשבון זה. ניתן לקריאה עם הרשאות צפייה, כך שחבר צוות רואה את אותה תשובה שהבעלים רואה.

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

{ "success": true, "cutover_enabled": true }

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

השיחות הישנות יותר, המעוצבות לפי קמפיינים #

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

• PUT /channel-routing/{channel} עם { "campaignId": "cp5NbV8xQrT2wYzA" } — נותן שם לקמפיין, והסוכן של אותו קמפיין הופך למשיב של הערוץ. { "campaignId": null } מנקה את הערוץ. קמפיין המיועד ליציאה בלבד נדחה מכיוון שאין לו התנהגות נכנסת להציע.
• POST /channel-routing/clear עם { "channels": ["whatsapp", "instagram"] } — משחרר מספר ערוצים מכל סוכן שעונה להם בשיחה אחת, בדרך כלל לפני הפנייתם למקום אחר. התגובה מפרטת את released_channels, אלו שבאמת היה להם משיב.

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

שגיאות API של נקודות כניסה (Entry Points) #

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

{
  "success": false,
  "error": "Entry point not found"
}

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

צעדים הבאים #

• נקודות כניסה (Entry Points) — הקונספט, סוגי הכללים, והפאנל מי עונה לשיחות חדשות באפליקציה.
• API של סוכני AI — יצירה והגדרה של הסוכנים שאליהם הכללים הללו מנתבים.
• API של ערוצים — חיבור הערוצים עצמם.
• אוטומציית תגובה להודעה פרטית — מה כללי התגובה עושים ברגע שהם מופעלים.