קטלוג אירועים

לכל גוף webhook יש שדה type שהערך שלו הוא אחד מסוגי האירועים בדף זה. כשאתם נרשמים לנקודת קצה, מערך events חייב להכיל את סוגי האירועים הרצויים לכם (או להיות ריק כדי להירשם לכל האירועים). שני סגנונות מסירה מעבירים אירועים אלה:

מסירות לנקודת קצה הן תמיד התראות שאינן חוסמות עם ניסיונות חוזרים: השיבו עם כל 2xx; המעטפה כוללת event_id למניעת כפילויות.
חילופים חוסמים פועלים רק ב- webhook מדור קודם עם כתובת URL יחידה: בקשת התצורה של telephony.incoming / web.incoming (מספרים במצב webhook ומפתחות וידג’ט, זמן קצוב של 10 שניות) ושיגור כלים במצב webhook. התגובה שלכם מעצבת את השיחה החיה.

דוגמאות המטענים להלן מציגות את מעטפת נקודת הקצה בסדר ההעברה שלה (מפתחות ממוינים בסדר אלפביתי: data, event_id, type); מסירות מדור קודם כוללות את אותו data ללא event_id.

אירועי שיחות

`telephony.incoming`

נשלח כאשר שיחה נכנסת מגיעה לאחד ממספרי הטלפון שלכם. מסירות לנקודות קצה הן התראות ללא המתנה הנשלחות עבור כל שיחה נכנסת, בין אם המספר מוגדר עם סוכן או עם webhook. מספרים ללא סוכן מוקצה מקבלים בנוסף את בקשת התצורה החוסמת ב-webhook מדור קודם — ראו telephony.incoming / web.incoming עבור סכימת הבקשה / התגובה המלאה.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

נשלח כאשר שיחת טלפוניה נכנסת או יוצאת מסתיימת. לא חוסם. כולל את התמליל המלא, כתובת ה-URL של ההקלטה וסיכום החיוב. ראו telephony.complete / web.complete עבור סכימת המטען.

`telephony.tool`

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

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response היא תוצאת הביצוע: {"status": <http status>, "response": <your endpoint's JSON>} במקרה של הצלחה, או {"status": <status>, "error": "<message>"} במקרה של כישלון.

`web.incoming`

המקבילה בערוץ האינטרנט של telephony.incoming, הנשלחת כאשר סשן של וידג’ט אינטרנט או שיחת בדיקת מיקרופון בבונה מתחילים. מסירות לנקודות קצה הן ללא המתנה עבור כל סשן אינטרנט. מפתחות הניתנים לפרסום ב-mode="webhook" מקבלים בנוסף את בקשת התצורה החוסמת ב-webhook מדור קודם — לבקשה החוסמת מבנה שונה (origin_domain, publishable_key_prefix; ללא מספרי טלפון). ראו telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number הוא תמיד המחרוזת המילולית "web". עבור סשני וידג’ט במצב webhook, to_number ריק (מספר הסוכן של הסשן מוקצה לאחר התצורה); עבור שיחות בדיקת מיקרופון בבונה, origin_domain ו- publishable_key_prefix ריקים.

`web.complete`

המקבילה בערוץ האינטרנט של telephony.complete, המכסה שיחות וידג’ט אינטרנט (direction: "web") ושיחות בדיקת מיקרופון בבונה (direction: "test"). לא חוסם. מבנה מטען זהה ל- telephony.complete, בתוספת origin_domain, כאשר from_number מוגדר ל-"web".

ב-webhook מדור קודם בעל כתובת URL יחידה, שיחות בדיקת מיקרופון בבונה מדווחות היסטורית כ-telephony.complete — רק שיחות עם direction: "web" משתמשות שם בסוג web.complete. מערכת נקודות הקצה ממפה גם שיחות אינטרנט וגם שיחות בדיקה אל web.*. מטענים היסטוריים עשויים להכיל את ערכי direction מדור קודם widget או mic.

`web.tool`

המקבילה בערוץ האינטרנט של telephony.tool. השדה data מכיל origin_domain במקום from_number / to_number.

אירועי איכות

`call.graded`

נשלח בכל פעם שהרצת דירוג AI מסתיימת עבור שיחה. לא חוסם.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

שדה	סוג	תיאור
`grade.id`	integer	מזהה הדירוג
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` או `no_conversation`
`grade.summary`	string	סיכום בפסקה אחת
`grade.detected_issues`	array	מחרוזות בעיות שאותרו על ידי המדרג
`grade.status`	string	תמיד `completed` — רק הרצות שהסתיימו מפיקות אירוע
`grade.grader_model`	string	המדרג שהפיק את התוצאה (לדוגמה, `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

אפשר לדרג שיחה יותר מפעם אחת — לעיתים קרובות דירוג היוריסטי מהיר מלווה בדירוג מודל מלא לאחר שההקלטה זמינה, ואפשר גם לבצע דירוגים מחדש ידניים. כל הרצה שהסתיימה מפיקה אירוע call.graded משלה; התייחסו ל-graded_at העדכני ביותר כסמכותי.

`issue.reported`

נשלח כאשר דוח בעיה נוצר — בין אם הוגש על ידי משתמש מלוח הבקרה (source: "user") או אוטומטית על ידי דירוג שיחות (source: "system"). לא חוסם.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

שדה	סוג	תיאור
`issue_report.severity`	string	`critical`, `warning` או `info`
`issue_report.status`	string	`open` או `resolved`
`issue_report.source`	string	`user` (הוגש מלוח הבקרה) או `system` (נוצר על ידי דירוג)

דירוג מחדש של שיחה בונה מחדש את דוחות הבעיה שנוצרו על ידי המערכת, ולכן מפיק שוב את issue.reported עבור הדוחות שנוצרו מחדש. בצעו ביטול כפילויות לפי call_id + title אם אתם רוצים התראה אחת בלבד לכל בעיה בסיסית.

אירועי שיחות בדיקה

`test-call.completed`

נשלח כאשר הרצת שיחת בדיקה מגיעה לסטטוס סופי — completed או failed, כולל הרצות שנכשלו בהפעלה ומעולם לא יצרו שיחה. לא חוסם. שימושי לחיבור הרצות CI באצווה למערכות הצ’אט/ההתראות שלכם.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

שדה	סוג	תיאור
`test_call_run.target_type`	string	`agent` או `phone_number`
`test_call_run.target_id`	integer	מזהה הסוכן או מזהה מספר הטלפון שאליו כוונה ההרצה, בהתאם ל-`target_type`
`test_call_run.status`	string	`completed` או `failed`
`test_call_run.call_id`	integer \| null	`null` כאשר ההרצה נכשלה לפני שבוצעה שיחה
`test_call_run.error_message`	string	ריק במקרה של הצלחה

אירועי התראות

`alert.triggered`

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

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

שדה	סוג	תיאור
`event_id` (ב-`data`)	UUID	מזהה ההפעלה של ההתראה — שונה מ-`event_id` של מסירת המעטפת
`rule_id`, `rule_name`	UUID, מחרוזת	הכלל שהופעל
`metric`	מחרוזת	`success_rate`, `failure_rate`, `avg_score`, `call_volume` או `suite_regression`
`comparator`	מחרוזת	`lt`, `lte`, `gt` או `gte`
`metric_value`	מספר	ערך המדד בחלון בעת הפעלת הכלל
`threshold`	מספר	הסף שהוגדר
`window_hours`	מספר שלם	חלון הערכה נגרר
`fired_at`	חותמת זמן

עיינו במדריך ההתראות ליצירת כללים, מדדים, תקופות צינון וערוצי הדוא”ל / Slack.

קשור

telephony.incoming / web.incoming

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

telephony.complete / web.complete

תמלול ומדדים לאחר השיחה.

נקודות קצה של Webhook

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

כלי פונקציות

כיצד נוצרים אירועי telephony.tool / web.tool.

Webhooks

Function Tools

קטלוג אירועים

אירועי שיחות

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

אירועי איכות

`call.graded`

`issue.reported`

אירועי שיחות בדיקה

`test-call.completed`

אירועי התראות

`alert.triggered`

קשור

telephony.incoming / web.incoming

telephony.complete / web.complete

נקודות קצה של Webhook

כלי פונקציות

​אירועי שיחות

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​אירועי איכות

​call.graded

​issue.reported

​אירועי שיחות בדיקה

​test-call.completed

​אירועי התראות

​alert.triggered

​קשור

telephony.incoming / web.incoming

telephony.complete / web.complete

נקודות קצה של Webhook

כלי פונקציות

אירועי שיחות

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

אירועי איכות

`call.graded`

`issue.reported`

אירועי שיחות בדיקה

`test-call.completed`

אירועי התראות

`alert.triggered`

קשור