Open in

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

כל סוגי אירועי ה-webhook ש-ThunderPhone מפיק.

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

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

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

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

אירועי שיחות

`telephony.incoming`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`telephony.complete`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`telephony.tool`

נשלח לאחר ששיחת טלפוניה מפעילה כלי פונקציה. התראת ביקורת שאינה חוסמת — הכלי כבר בוצע בעת מסירת אירוע זה; הוא מכסה כלי פונקציה משלכם ואת הכלי המובנה send_sms (ולא כלים מובנים אחרים, כלי בסיס ידע, חיבורי אפליקציות או כלי MCP). עבור send_sms, גם arguments.to וגם arguments.body הם [REDACTED]. גם תמלולי השלמה מצנזרים אותם; אחזרו את התוכן ואת הנמען ממשאב ה-SMS ברמת הארגון באמצעות message_id שבתגובה.

{
  "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>"} במקרה של כישלון.

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`telephony.turn`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`position`	integer	האינדקס של התור בהיסטוריית השיחה — מזהה יציב למיון
`role`	string	`assistant` (דיבור של הסוכן) או `user` (דיבור של המתקשר)
`text`	string	טקסט התמלול של התור כפי שהיה ידוע בעת הפליטה
`entry_type`	string	סוג רשומת ההיסטוריה הבסיסית: `completion` (סוכן), או `user_turn` / `span` (מתקשר)
`start_ms`, `end_ms`	integer	היסטי שמע באלפיות שנייה מתחילת השיחה; קיימים רק כאשר תזמון ההשמעה כבר היה ידוע בעת הפליטה

`web.incoming`

המקביל בערוץ האינטרנט של telephony.incoming, נשלח כאשר סשן של ווידג'ט אינטרנט או שיחת בדיקת מיקרופון בבונה מתחילים. משלוחים לנקודת קצה הם מסוג fire-and-forget עבור כל סשן אינטרנט. מפתחות הניתנים לפרסום במצב 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 ריקים.

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`web.complete`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`web.tool`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`web.turn`

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן

`call.transfer_completed`

נשלח פעם אחת לכל שיחה עם התוצאה הסופית של העברת שיחה: העברה קרה, או הגישור בין האנשים שהעברה חמה משאירה לאחר שהסוכן יוצא מהשיחה. אינו חוסם, ונמסר לנקודות קצה בלבד (לעולם לא ל-webhook מדור קודם עם כתובת URL יחידה). הוא מגיע לאחר telephony.complete של השיחה: כאשר הספק מקבל את השיחה או שההעברה נכשלת, או, כאשר ThunderPhone גישרה על השיחה, לאחר סיום הגישור.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

שדה	סוג	תיאור
`call_id`	מספר שלם	השיחה שהועברה
`agent_id`	מספר שלם \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	מחרוזת \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`transfer_outcome`	מחרוזת	`refer_accepted`: הספק קיבל את השיחה. `bridged`: ThunderPhone שמרה בעצמה על החיבור בין המתקשר ליעד, בין שהספק סירב להעברה קרה ובין שהסוכן של העברה חמה יצא מהשיחה. `bridge_unanswered`: הספק סירב להעברה קרה והיעד לא ענה לשיחה ש-ThunderPhone ביצעה בעצמה. `failed`: ההעברה לא הושלמה והשיחה הסתיימה
`destination`	מחרוזת \| null	המספר שאליו הועברה השיחה
`sip_status`	מספר שלם \| null	סטטוס ה-SIP של הספק כאשר סירב להעברה הקרה: `403` (לדוגמה, trunk של Twilio ללא העברת שיחות), `405` או `501`. הערך `null` כאשר הספק לא סירב לה
`bridge_kind`	מחרוזת \| null	עבור `bridged` בלבד: `cold_fallback` (העברה קרה שסורבה ו-ThunderPhone חיברה) או `warm` (שני האנשים בהעברה חמה לאחר שהסוכן עזב)
`bridge_seconds`	מספר שלם \| null	עבור `bridged` בלבד: זמן הגישור ש-ThunderPhone חייבה עליו, בשניות
`bridge_total_cents`	מספר שלם \| null	עבור `bridged` בלבד: עלות הגישור בסנטים של USD לאחר כל זיכוי שיחה חינמי, בחיוב נפרד מ-`billing_total_cents` של השיחה

אותם הערכים נמצאים גם ב-אובייקט השיחה בתור transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds ו- transfer_bridge_total_cents. הערך event_id זהה בכל מסירה עבור שיחה, ולכן דיווח חוזר לעולם אינו יוצר אירוע שני.

אירועי SMS

אירועי SMS מתארים הודעות שנשלחו דרך חשבון Twilio או Telnyx המחובר של הארגון. גוף ההודעה מושמט, והשדה to מושחר. אחזרו את ההודעה ברמת הארגון באמצעות GET /v1/sms/{message_id} כאשר נדרשים התוכן שלה או הנמען.

`sms.sent`

נשלח כאשר המפעיל הסלולרי של הלקוח מקבל בקשת SMS יוצאת. זו אינה אישור מסירה למכשיר.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

`sms.failed`

נשלח לאחר דחייה קבועה מצד המפעיל הסלולרי, לאחר שמוצו ניסיונות חוזרים זמניים, או כאשר התוצאה אינה ידועה באופן סופי. error_code הוא קוד יציב של ThunderPhone, ו-error_message מציין את הפעולה שעל הלקוח לבצע כאשר היא זמינה. status: "unknown" פירושו שהמפעיל הסלולרי עשוי היה לקבל את הודעת ה-SMS; התאימו אותה לרשומת המפעיל הסלולרי, משום ש-ThunderPhone לא ישלח אותה מחדש באופן אוטומטי.

`sms.received`

שמור לתמיכה ב-SMS נכנס. בגרסה הנוכחית לא נפלטים אירועי sms.received. הגדרת webhook נכנס של המפעיל הסלולרי ואימות חתימה יישלחו בנפרד.

אירועי קול

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

voice.ready ו-voice.failed נמסרים רק לנקודת קצה כלל-ארגונית עם 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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`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
`report`	object \| null	דוח השיחה המוצג ללקוח: תווית תוצאה, דגל נדרשת תשומת לב והסיבה לכך, המתקשר, סיכום בשורה אחת וחוויית המתקשר. בדירוג היוריסטי מוקדם הוא `null` או דוח `pending` שהשדות בו הם מצייני מקום; האירוע של הדירוג המלא כולל את הדוח שהושלם

`call.data_extracted`

נשלח בכל פעם שחילוץ נתונים מובנים מסתיים בהצלחה, כולל ניסיון חוזר מאוחר לאחר telephony.complete / web.complete או הפעלה חוזרת ידנית באמצעות POST /v1/calls/{call_id}/extract. לא חוסם.

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

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`summary`	string \| null	סיכום השיחה שהושלם כאשר האפשרות יצירת סיכום שיחה מופעלת אצל הסוכן, כך שאירוע חילוץ מאוחר מספק גם סיכום שהחמיץ את חלון ההשלמה; אחרת `null`. סוכנים עם סיכום אך ללא שדות חילוץ אינם שולחים אירוע זה: קראו סיכום מאוחר מתוך `GET /v1/calls/{call_id}`
`extracted_data.status`	string	תמיד `completed` עבור אירוע זה
`extracted_data.fields`	object	ערכים לפי מפתחות שדות החילוץ שהוגדרו; ערכים שאינם זמינים הם `null`
`extracted_data.evidence`	object	ראיות לפי שדה חילוץ. ערך שאינו null כולל את הציטוט המדויק שנבדק מבנית (עד 1,000 תווים), את `speaker_role` (`caller` או `agent`) ואת `turn_index`; ציטוטים ארוכים יותר שהוחזרו על ידי המודל נדחים במקום להיחתך, והראיות הן `null` בכל פעם שהשדה שלהן הוא `null`
`extracted_data.verification`	string	`verified` רק כאשר מעבר הראיות העצמאי החזיר בדיוק פסק דין תקין אחד לכל שדה מועמד. `unavailable` מציין שהמעבר נכשל, חרג מזמן ההמתנה, לא כלל תקציב מספיק או החזיר פלט פגום או חלקי. מעבר שאינו זמין לחלוטין שומר ערכים המבוססים מבנית לצורך בדיקת לקוחות. בפלט חלקי, פסקי דין תקינים מוחלים וכל מועמד ללא בדיוק פסק דין תקין אחד מאופס ל-null
`extracted_data.field_reasons`	object	סיבות לפי שדות שאופסו ל-null על ידי ביסוס מבני או המאמת העצמאי
`extracted_data.schema_version`	string	גיבוב של סכמת השדות המדויקת ששימשה לחילוץ זה
`extracted_at`	timestamp	זמן השלמה בתקן ISO 8601
`model`	string	המודל ששימש לחילוץ

`campaign.completed`

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

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

ארבע ספירות התוצאות נפרדות זו מזו וסכומן הוא contacts_total: completed כולל אנשי קשר שהושלמו בהצלחה; no_answer כולל אנשי קשר שנכשלו או שמוצו באופן סופי, ושמענה לא התקבל כתוצאה הסופית שלהם; failed כולל את כל אנשי הקשר האחרים שנכשלו או שמוצו באופן סופי; ו-remaining כולל אנשי קשר ממתינים, מתוזמנים או שנמצאים כרגע בשיחה. איש קשר הממתין לניסיון חוזר הוא remaining, גם כאשר הניסיון האחרון שלו הסתיים ללא מענה. שיחות שנמצאות בתהליך מותאמות לפני תמונת מצב ההשלמה החד-פעמית. started_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"
}

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`issue_report.severity`	string	`critical`, `warning` או `info`
`issue_report.status`	string	`open` או `resolved`
`issue_report.source`	string	`user` (נשלח מלוח הבקרה) או `system` (נוצר על ידי דירוג)

`issue.escalated`

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

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

שדה	סוג	תיאור
`automatic`	boolean	`true` עבור הסלמה אוטומטית; `false` עבור הסלמה ידנית
`cluster_id`	UUID	דפוס הבעיה שהוסלם
`escalation_id`	UUID	רשומת ההסלמה
`status`	string	`open` כאשר האירוע נשלח

זוהי התראה, ולא חבילת הראיות. השתמשו ב-cluster_id כדי לקשר אותה לדפוס הבעיה. ראו דיווח ל-ThunderPhone.

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

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

שדה	סוג	תיאור
`agent_id`	integer \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`agent_name`	string \| null	הסוכן שטיפל בשיחה, כאשר הוקצה סוכן
`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, string	הכלל שהופעל
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume` או `suite_regression`
`comparator`	string	`lt`, `lte`, `gt` או `gte`
`metric_value`	number	ערך המדד בחלון בזמן הפעלת הכלל
`threshold`	number	הסף שהוגדר
`window_hours`	integer	חלון ההערכה הקודם
`fired_at`	timestamp

עיינו במדריך ההתראות כדי ליצור כללים, מדדים, זמני המתנה וערוצי דוא״ל / Slack.

אירועי הגירה

`migration.call.complete`

נשלח כאשר שיחה שהתחלתם באמצעות POST /v1/migrations/{id}/calls מסתיימת, ללא קשר לפלטפורמה שטיפלה בה. אינו חוסם. הוא מגיע עד כ-5 דקות לאחר סיום השיחה. data כולל כל שדה של telephony.complete בתוספת בלוק migration. שיחה ש-ThunderPhone התחילה שולחת גם telephony.complete כרגיל, עם אותו call_id. שיחה בפלטפורמה האחרת שלא הסתיימה לאחר שעתיים, או שההגירה שלה הסתיימה או איבדה את המפתח שלה קודם לכן, נשלחת עם status: "unknown" וללא תמליל.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

שדה	סוג	תיאור
`migration.id`	UUID	ההגירה
`migration.routing_id`	UUID	השיחה שנותבה, כפי שהוחזר כשהתחלתם אותה
`migration.arm`	string	`ours` ‏(ThunderPhone התחילה אותה) או `vendor` ‏(הפלטפורמה האחרת התחילה אותה)
`migration.vendor`	string	`retell`, `vapi`, `elevenlabs` או `bland`
`migration.vendor_call_id`	string \| null	מזהה השיחה של הפלטפורמה האחרת; `null` עבור `ours`
`migration.metadata`	object	ה-`metadata` ששלחתם בעת התחלת השיחה
`migration.vendor_cost_usd`	string \| null	העלות שהפלטפורמה האחרת דיווחה עבורה לשיחה, אם דיווחה
`call_id`	integer \| null	מזהה השיחה של ThunderPhone; ‏`null` עבור `vendor`
`status`	string	עבור `vendor`: ‏`completed` כאשר הנמען דיבר, `failed` כאשר לא דיבר, `unknown` כמפורט לעיל. עבור `ours`: כמו ב-`telephony.complete`

עבור שיחת vendor, ל-ThunderPhone אין נתוני חיוב או חילוץ: billable_minutes, billing_total_cents ו-extracted_data הם null, product ו-voice ריקים, recording_mode הוא vendor, ו- recording_url הוא הקישור של הפלטפורמה האחרת, אם סיפקה קישור.

`migration.rollback`

נשלח כאשר המעבר ההדרגתי של הגירה מחזיר את כל השיחות לפלטפורמה האחרת באופן אוטומטי: 3 שיחות לא הצליחו להתחבר ל-ThunderPhone בתוך 15 דקות, 2 שיחות שנשלחו ל-ThunderPhone הסתיימו לפני שהסוכן ענה, או ששיעור תוצאות המשימות של ThunderPhone ירד ביותר מהפער שהוגדר מתחת לזה של הפלטפורמה האחרת. לא חוסם, פעם אחת לכל חזרה לאחור. לאחר מכן, חלקה של ThunderPhone הוא 0% וההגירה מושהית עד שמישהו מחדש אותה בכרטיסייה הגירה של הסוכן. המטען אינו כולל מספרי טלפון, תמלילים או מזהי שיחות.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

שדה	סוג	תיאור
`migration_id`	UUID	ההגירה
`vendor`	מחרוזת	`retell`, `vapi`, `elevenlabs` או `bland`
`reason`	מחרוזת	`ours_failed_burst` ‏(3 חיבורים שנכשלו בתוך 15 דקות), `dropped_calls` ‏(2 שיחות שהסתיימו לפני שהסוכן ענה, בתוך 30 דקות), או `rate_gap` ‏(פער בשיעור תוצאות המשימות על פני לפחות `rollback_min_calls` שיחות מדורגות לכל צד)
`previous_percent`	מספר שלם	חלקה של ThunderPhone בשיחות לפני החזרה לאחור
`ours_percent`	מספר שלם	תמיד `0`
`step`	מספר שלם \| null	שלב לוח הזמנים שבו הייתה ההגירה (בספירה המתחילה ב-0)
`ours` / `theirs`	אובייקט \| null	שיחות מדורגות בשלב הנוכחי ושיעור ההצלחה שלהן; `theirs` עשוי לייצג את 30 הימים האחרונים כאשר לשלב יש מעט מדי שיחות. `null` כאשר לא היו שיחות
`ours_failed`	מספר שלם	חיבורים שנכשלו ונספרו ב-15 הדקות האחרונות
`dropped`	מספר שלם	שיחות שנספרו כניתוק ב-30 הדקות האחרונות
`rolled_back_at`	חותמת זמן

קשור

telephony.incoming / web.incoming

מטען הנתונים החוסם של שיחה נכנסת, שעליכם להשיב לו.

telephony.complete / web.complete

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

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

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

כלי פונקציות

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