Ereigniskatalog

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

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

Die folgenden Beispiel-Payloads zeigen den Endpunkt-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. Endpoint-Zustellungen 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 — siehe telephony.incoming / web.incoming für das vollständige Anfrage-/Antwortschema.

{
  "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 Telefonanruf endet. Nicht blockierend. Enthält das vollständige Transkript, die Aufzeichnungs-URL und die Abrechnungszusammenfassung. Siehe telephony.complete / web.complete für das Nutzlastschema.

`telephony.tool`

Wird gesendet, nachdem ein Telefonanruf ein Funktionstool aufgerufen hat. Nicht blockierende Audit-Benachrichtigung — das Tool wurde bereits ausgeführt, wenn dieses Ereignis zugestellt wird; es umfasst Ihre eigenen Funktionstools (keine integrierten 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: {"status": <http status>, "response": <your endpoint's JSON>} bei Erfolg oder {"status": <status>, "error": "<message>"} bei Fehlern.

`web.incoming`

Das Webkanal-Äquivalent von telephony.incoming, das gesendet wird, wenn eine Web-Widget-Sitzung oder ein Builder-Mikrofontestanruf beginnt. Endpoint-Zustellungen 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 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") umfasst. Nicht blockierend. Dieselbe Nutzlaststruktur wie telephony.complete, zusätzlich 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 Endpoint-System ordnet sowohl Web- als auch Testanrufe web.* zu. Historische Nutzlasten können die Legacy-Werte widget oder mic für direction enthalten.

`web.tool`

Das Webkanal-Äquivalent von telephony.tool. data enthält origin_domain anstelle von from_number / to_number.

Qualitätsereignisse

`call.graded`

Wird gesendet, wenn ein KI-Bewertungsdurchlauf für einen Anruf abgeschlossen ist. 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 erzeugt hat (z. B. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Ein Anruf kann mehr als einmal bewertet werden — auf eine schnelle heuristische Bewertung folgt häufig eine vollständige Modellbewertung, sobald die Aufzeichnung verfügbar ist, und manuelle Neubewertungen sind möglich. Jeder abgeschlossene Durchlauf sendet ein eigenes call.graded-Ereignis; behandeln Sie das neueste graded_at als maßgeblich.

`issue.reported`

Wird gesendet, wenn ein Problembericht erstellt wird — entweder von einem Benutzer über das 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 Testanrufdurchlauf 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-/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 Telefonnummern-ID, auf die der Durchlauf abzielte, entsprechend `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 getätigt wurde
`test_call_run.error_message`	string	Bei Erfolg leer

Warnungsereignisse

`alert.triggered`

Wird gesendet, wenn eine Warnungsregel mit aktiviertem Kanal An Entwickler-Webhooks zustellen ihren Schwellenwert überschreitet. Nicht blockierend. Eine Regel wird einmal ausgelöst und berücksichtigt dann ihre Abklingzeit. Ein anhaltender Verstoß erzeugt daher ein Ereignis pro Abklingzeitfenster.

{
  "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 der Warnung — unterscheidet sich von der `event_id` für die Zustellung im Envelope
`rule_id`, `rule_name`	UUID, Zeichenfolge	Die ausgelöste Regel
`metric`	Zeichenfolge	`success_rate`, `failure_rate`, `avg_score`, `call_volume` oder `suite_regression`
`comparator`	Zeichenfolge	`lt`, `lte`, `gt` oder `gte`
`metric_value`	Zahl	Der Wert der Metrik über das Fenster, als die Regel ausgelöst wurde
`threshold`	Zahl	Der konfigurierte Schwellenwert
`window_hours`	Ganzzahl	Rückblickendes Auswertungsfenster
`fired_at`	Zeitstempel

Informationen zum Erstellen von Regeln, Metriken, Abklingzeiten sowie den E-Mail- und Slack-Kanälen finden Sie im Warnungen-Leitfaden.

telephony.incoming / web.incoming

Die blockierende Payload 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

Wie telephony.tool- und web.tool-Ereignisse generiert werden.

Webhooks

Function Tools

Anrufereignisse

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Qualitätsereignisse

`call.graded`

`issue.reported`

Testanrufereignisse

`test-call.completed`

Warnungsereignisse

`alert.triggered`

Verwandte Inhalte

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

​Qualitätsereignisse

​call.graded

​issue.reported

​Testanrufereignisse

​test-call.completed

​Warnungsereignisse

​alert.triggered

​Verwandte Inhalte

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`

Qualitätsereignisse

`call.graded`

`issue.reported`

Testanrufereignisse

`test-call.completed`

Warnungsereignisse

`alert.triggered`

Verwandte Inhalte