ThunderPhone 2.0 באוויר.בשירות עצמי, החל מ-2¢/דקה.קראו את הודעת ההשקה
בואו נתחיל

Webhooks

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

כל סוגי אירועי ה-webhook ש-ThunderPhone שולחת.

לכל גוף וובהוק יש שדה type שהערך שלו הוא אחד מסוגי האירועים בדף זה. בעת הרשמה אל נקודת קצה, מערך ה-events חייב לכלול את סוגי האירועים הרצויים לכם (או להיות ריק כדי להירשם לכל האירועים — למעט אירועי כל תור telephony.turn / web.turn, שנמסרים רק לנקודות קצה שמציינות אותם במפורש).

שני סגנונות מסירה נושאים אירועים אלה:

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

אירועי שיחות

telephony.incoming

נשלח כאשר שיחה נכנסת מגיעה לאחד ממספרי הטלפון שלכם. מסירות לנקודות קצה הן התראות ללא המתנה לתגובה הנשלחות עבור כל שיחה נכנסת, בין אם המספר מוגדר לסוכן או מוגדר לוובהוק. מספרים ללא סוכן משויך מקבלים בנוסף את בקשת התצורה החוסמת בוובהוק מדור קודם — עיינו ב- 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>"} בכישלון.

telephony.turn

נשלח במהלך שיחת טלפוניה פעילה, פעם אחת עבור כל תור הכולל דיבור בעת התרחשותו — ההשלמות המדוברות של הסוכן והתורים המתומללים של המתקשר. מאפשר לעקוב אחר השיחה החיה באמצעות וובהוקים רגילים במקום לבצע תשאול של GET /v1/calls/{call_id}/transcript. אינו חוסם.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}
שדהסוגתיאור
positionintegerהאינדקס של התור בהיסטוריית השיחה — מזהה יציב לצורך מיון
rolestringassistant (דיבור הסוכן) או user (דיבור המתקשר)
textstringטקסט תמלול התור כפי שהיה ידוע בזמן השליחה
entry_typestringסוג רשומת ההיסטוריה הבסיסית: completion (סוכן), או user_turn / span (מתקשר)
start_ms, end_msintegerהיסטי שמע באלפיות שנייה מתחילת השיחה; קיימים רק כאשר תזמון ההשמעה כבר היה ידוע בזמן השליחה

web.incoming

המקבילה בערוץ האינטרנטי של telephony.incoming, נשלחת כאשר סשן של רכיב אינטרנט או שיחת בדיקת מיקרופון של הבונה מתחילים. מסירות לנקודות קצה הן ללא המתנה לתגובה עבור כל סשן אינטרנטי. מפתחות הניתנים לפרסום במצב mode="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". עבור סשני רכיב במצב וובהוק, to_number ריק (מספר הסוכן של הסשן מוקצה לאחר התצורה); עבור שיחות בדיקת מיקרופון של הבונה, origin_domain ו- publishable_key_prefix ריקים.

web.complete

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

web.tool

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

web.turn

המקבילה בערוץ האינטרנטי של telephony.turn, המכסה שיחות רכיב אינטרנט ושיחות בדיקת מיקרופון של הבונה. אותו מבנה מטען, עם origin_domain במקום from_number / to_number. כמו telephony.turn, היא דורשת הרשמה מפורשת — היא לעולם אינה נמסרת באמצעות מערך events ריק.

אירועי קול

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

voice.ready

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

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed

נשלח כאשר עיבוד של קול מותאם אישית מגיע לכשל קבוע.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}
שדהסוגתיאור
voice.idמחרוזתמזהה ציבורי של קול מותאם אישית
voice.nameמחרוזתערך הקול של הסוכן בתבנית custom:<public_id>
voice.display_nameמחרוזתשם הקול המוצג לארגון
voice.languageמחרוזתקוד השפה היחידה של השכפול
voice.genderמחרוזתmale, female או מחרוזת ריקה
voice.statusמחרוזתready עבור voice.ready; ‏failed עבור voice.failed
voice.failure_reasonמחרוזתריק בהצלחה; פרטי כשל העיבוד במקרה של כשל
voice.created_at, voice.updated_atחותמת זמןחותמות זמן בתקן ISO 8601
reasonמחרוזתפרטי הכשל; קיים רק ב-voice.failed

אירועי איכות

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מספר שלםמזהה הדירוג
grade.scoreמספר שלם | null0–100
grade.call_outcomeמחרוזתsuccess, failure, unknown או no_conversation
grade.summaryמחרוזתסיכום בפסקה אחת
grade.detected_issuesמערךמחרוזות של בעיות שאותרו על ידי המדרג
grade.statusמחרוזתתמיד completed — רק הרצות שהסתיימו פולטות אירוע
grade.grader_modelמחרוזתהמדרג שהפיק את התוצאה (לדוגמה, heuristic-v1)
grade.graded_at, grade.created_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מחרוזתcritical, warning או info
issue_report.statusמחרוזתopen או resolved
issue_report.sourceמחרוזתuser (נשלח מלוח הבקרה) או system (נוצר על ידי דירוג)

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

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מחרוזתagent או phone_number
test_call_run.target_idמספר שלםמזהה הסוכן או מספר הטלפון שמטרת ההרצה הייתה אליו, בהתאם ל-target_type
test_call_run.statusמחרוזתcompleted או failed
test_call_run.call_idמספר שלם | nullnull כאשר ההרצה נכשלה לפני שבוצעה שיחה
test_call_run.error_messageמחרוזתריק במקרה של הצלחה

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

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_nameUUID, מחרוזתהכלל שהופעל
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.