Ereigniskatalog - ThunderPhone

Jeder Webhook-Body hat ein Feld type, dessen Wert einer der Ereignistypen auf dieser Seite ist. Wenn Sie einen Endpoint abonnieren, muss das Array events die gewünschten Ereignistypen enthalten (oder leer sein, um alles zu abonnieren). Diese Ereignisse werden auf zwei Arten zugestellt:

Endpoint-Zustellungen sind immer nicht blockierende Benachrichtigungen mit Wiederholungsversuchen: Antworten Sie mit einem beliebigen 2xx-Status; der Umschlag enthält eine event_id zur Deduplizierung.
Blockierende Austausche laufen nur über den Legacy-Webhook mit einzelner URL: die Konfigurationsanfrage telephony.incoming / web.incoming (Nummern im Webhook-Modus und Widget-Schlüssel, 10-s-Timeout) sowie die Tool-Weiterleitung im Webhook-Modus. Ihre Antwort bestimmt den Live-Anruf.

Die folgenden Beispiel-Payloads zeigen den Endpoint-Umschlag in seiner Übertragungsreihenfolge (Schlüssel alphabetisch sortiert: data, event_id, type); Legacy-Zustellungen enthalten dieselben data ohne event_id.

Anrufereignisse

`telephony.incoming`

Wird gesendet, wenn ein eingehender Anruf eine Ihrer Telefonnummern erreicht. Zustellungen an Endpunkte sind Fire-and-forget-Benachrichtigungen, die für jeden eingehenden Anruf gesendet werden, unabhängig davon, ob die Nummer für einen Agenten oder einen Webhook konfiguriert ist. Nummern ohne zugewiesenen Agenten erhalten zusätzlich die blockierende Konfigurationsanfrage über den Legacy-Webhook — das vollständige Anfrage-/Antwortschema finden Sie unter 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`

Wird gesendet, wenn ein eingehender oder ausgehender Telefonieanruf endet. Nicht blockierend. Enthält das Transkript, die Aufzeichnungs-URL, sofern verfügbar, sowie eine Abrechnungsübersicht. Das Payload-Schema finden Sie unter telephony.complete / web.complete.

`telephony.tool`

Wird gesendet, nachdem ein Telefonieanruf ein Funktionstool aufruft. Nicht blockierende Audit-Benachrichtigung — das Tool wurde bereits ausgeführt, wenn dieses Ereignis zugestellt wird; es umfasst Ihre eigenen Funktionstools (nicht integrierte Tools, Wissensdatenbank-, App-Verbindungs- oder MCP-Tools).

{
  "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 ist das Ausführungsergebnis: Bei Erfolg {"status": <http status>, "response": <your endpoint's JSON>}, bei Fehlern {"status": <status>, "error": "<message>"}.

`web.incoming`

Das Webkanal-Äquivalent von telephony.incoming, das gesendet wird, wenn eine Web-Widget-Sitzung oder ein Builder-Mikrofontestanruf beginnt. Zustellungen an Endpunkte sind für jede Websitzung Fire-and-forget. Veröffentlichbare Schlüssel in mode="webhook" erhalten zusätzlich die blockierende Konfigurationsanfrage über den Legacy-Webhook — diese blockierende Anfrage hat eine andere Struktur (origin_domain, publishable_key_prefix; keine Telefonnummern). Siehe 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 ist immer der Literalwert "web". Bei Web-Widget-Sitzungen im Webhook-Modus ist to_number leer (die Agentennummer der Sitzung wird nach der Konfiguration zugewiesen); bei Builder-Mikrofontestanrufen sind origin_domain und publishable_key_prefix leer.

`web.complete`

Das Webkanal-Äquivalent von telephony.complete, das Web-Widget-Anrufe (direction: "web") und Builder-Mikrofontestanrufe (direction: "test") abdeckt. Nicht blockierend. Dieselbe Payload-Struktur wie bei telephony.complete, zusätzlich mit origin_domain, wobei from_number auf "web" gesetzt ist.

Beim Legacy-Webhook mit einer einzelnen URL werden Builder-Mikrofontestanrufe historisch als telephony.complete gemeldet — nur Anrufe mit direction: "web" verwenden dort den Typ web.complete. Das Endpunktsystem ordnet sowohl Web- als auch Testanrufe web.* zu. Historische Payloads können die Legacy-Werte widget oder mic für direction enthalten.

`web.tool`

Das Webkanal-Äquivalent von telephony.tool. Die data enthalten origin_domain statt from_number / to_number.

Sprachereignisse

Die Erstellung benutzerdefinierter Stimmen erfolgt asynchron. Mit diesen nicht blockierenden Ereignissen können Sie auf ein endgültiges Ergebnis reagieren, anstatt den Clone-Detail-Endpunkt abzufragen.

`voice.ready`

Wird gesendet, wenn die Verarbeitung einer benutzerdefinierten Stimme abgeschlossen ist und sie einem Agenten zugewiesen werden kann.

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

Wird gesendet, wenn die Verarbeitung einer benutzerdefinierten Stimme dauerhaft fehlschlägt.

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

Feld	Typ	Beschreibung
`voice.id`	string	Öffentliche ID der benutzerdefinierten Stimme
`voice.name`	string	Stimmenwert des Agenten im Format `custom:<public_id>`
`voice.display_name`	string	Für die Organisation sichtbarer Stimmenname
`voice.language`	string	Sprachcode der einzigen Sprache des Clones
`voice.gender`	string	`male`, `female` oder eine leere Zeichenfolge
`voice.status`	string	`ready` für `voice.ready`; `failed` für `voice.failed`
`voice.failure_reason`	string	Bei Erfolg leer; bei Fehler Details zum Verarbeitungsfehler
`voice.created_at`, `voice.updated_at`	timestamp	ISO-8601-Zeitstempel
`reason`	string	Fehlerdetails; nur bei `voice.failed` vorhanden

Qualitätsereignisse

`call.graded`

Wird gesendet, wenn eine KI-Bewertung für einen Anruf abgeschlossen wird. Nicht blockierend.

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

Feld	Typ	Beschreibung
`grade.id`	integer	Bewertungs-ID
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` oder `no_conversation`
`grade.summary`	string	Zusammenfassung in einem Absatz
`grade.detected_issues`	array	Vom Bewertungsmodul erkannte Problemzeichenfolgen
`grade.status`	string	Immer `completed` — nur abgeschlossene Durchläufe senden ein Ereignis
`grade.grader_model`	string	Welches Bewertungsmodell das Ergebnis erstellt hat (z. B. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Ein Anruf kann mehrmals bewertet werden — auf eine schnelle heuristische Bewertung folgt häufig eine vollständige Modellbewertung, sobald die Aufzeichnung verfügbar ist; auch manuelle Neubewertungen sind möglich. Jeder abgeschlossene Durchlauf sendet ein eigenes call.graded-Ereignis; betrachten Sie den neuesten Wert für graded_at als maßgeblich.

`issue.reported`

Wird gesendet, wenn ein Problembericht erstellt wird — entweder von einem Benutzer im Dashboard eingereicht (source: "user") oder automatisch durch die Anrufbewertung erstellt (source: "system"). Nicht blockierend.

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

Feld	Typ	Beschreibung
`issue_report.severity`	string	`critical`, `warning` oder `info`
`issue_report.status`	string	`open` oder `resolved`
`issue_report.source`	string	`user` (über das Dashboard eingereicht) oder `system` (durch die Bewertung erstellt)

Die Neubewertung eines Anrufs erstellt dessen systemgenerierte Problemberichte neu, wodurch issue.reported für die neu erstellten Berichte erneut gesendet wird. Deduplizieren Sie nach call_id + title, wenn Sie nur eine Benachrichtigung pro zugrunde liegendem Problem erhalten möchten.

Testanrufereignisse

`test-call.completed`

Wird gesendet, wenn ein Testanruf-Durchlauf einen Endstatus erreicht — completed oder failed, einschließlich Durchläufen, die beim Start fehlgeschlagen sind und nie einen Anruf erzeugt haben. Nicht blockierend. Nützlich, um Batch-CI-Durchläufe mit Ihren Chat- und Benachrichtigungssystemen zu verbinden.

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

Feld	Typ	Beschreibung
`test_call_run.target_type`	string	`agent` oder `phone_number`
`test_call_run.target_id`	integer	Die Agenten-ID oder Telefonnummer-ID, auf die der Durchlauf ausgerichtet war, passend zu `target_type`
`test_call_run.status`	string	`completed` oder `failed`
`test_call_run.call_id`	integer \| null	`null`, wenn der Durchlauf fehlgeschlagen ist, bevor ein Anruf aufgebaut wurde
`test_call_run.error_message`	string	Bei Erfolg leer

Alarmereignisse

`alert.triggered`

Wird gesendet, wenn eine Alarmregel mit aktiviertem Kanal An Entwickler-Webhooks senden ihren Schwellenwert überschreitet. Nicht blockierend. Eine Regel wird einmal ausgelöst und berücksichtigt anschließend ihren Cooldown, sodass eine anhaltende Überschreitung ein Ereignis pro Cooldown-Fenster erzeugt.

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

Feld	Typ	Beschreibung
`event_id` (in `data`)	UUID	Die Auslösungs-ID des Alarms — unterscheidet sich von der `event_id` der Zustellung im Umschlag
`rule_id`, `rule_name`	UUID, String	Die ausgelöste Regel
`metric`	String	`success_rate`, `failure_rate`, `avg_score`, `call_volume` oder `suite_regression`
`comparator`	String	`lt`, `lte`, `gt` oder `gte`
`metric_value`	Zahl	Der Wert der Metrik im Fenster, als die Regel ausgelöst wurde
`threshold`	Zahl	Der konfigurierte Schwellenwert
`window_hours`	Ganzzahl	Nachlaufendes Auswertungsfenster
`fired_at`	Zeitstempel

Im Leitfaden zu Alarmen erfahren Sie, wie Sie Regeln, Metriken, Cooldowns sowie die E-Mail- und Slack-Kanäle erstellen.

Verwandt

telephony.incoming / web.incoming

Die blockierende Nutzlast für eingehende Anrufe, auf die Sie antworten müssen.

telephony.complete / web.complete

Transkript und Metriken nach dem Anruf.

Webhook-Endpunkte

Abonnieren Sie eine URL für eine Teilmenge dieser Ereignisse.

Funktions-Tools

So werden Ereignisse von telephony.tool / web.tool generiert.

​Anrufereignisse

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Sprachereignisse

​voice.ready

​voice.failed

​Qualitätsereignisse

​call.graded

​issue.reported

​Testanrufereignisse

​test-call.completed

​Alarmereignisse

​alert.triggered

​Verwandt

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-Endpunkte

Funktions-Tools

Anrufereignisse

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Sprachereignisse

`voice.ready`

`voice.failed`

Qualitätsereignisse

`call.graded`

`issue.reported`

Testanrufereignisse

`test-call.completed`

Alarmereignisse

`alert.triggered`

Verwandt