Webhooks

Ereigniskatalog

Alle Webhook-Ereignistypen, die ThunderPhone ausgibt.

Jeder Webhook-Body hat ein Feld type, dessen Wert einer der Ereignistypen 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 — mit Ausnahme der Ereignisse pro Turn telephony.turn / web.turn, die nur an Endpunkte zugestellt werden, die sie explizit angeben).

Diese Ereignisse werden in zwei Zustellungsarten übertragen:

• Endpunkt-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 erfolgen nur über den Legacy-Single-URL-Webhook: die Konfigurationsanfrage telephony.incoming / web.incoming (Nummern und Widget-Schlüssel im Webhook-Modus, Timeout von 10 s) und der Tool-Versand im Webhook-Modus. Ihre Antwort beeinflusst 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 Telefonieanruf endet. Nicht blockierend. Enthält das Transkript, die Aufzeichnungs-URL, sofern verfügbar, sowie die Abrechnungsübersicht. Siehe telephony.complete / web.complete für das Payload-Schema.

telephony.tool#

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

telephony.turn#

Wird während eines Telefonieanrufs gesendet, der läuft, jeweils einmal für jeden sprachhaltigen Turn, sobald er erfolgt — die gesprochenen Antworten des Agenten und die transkribierten Turns des Anrufers. Damit können Sie die Live-Unterhaltung über einfache Webhooks verfolgen, statt GET /v1/calls/{call_id}/transcript abzufragen. Nicht blockierend.

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

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 Form (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 erst 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 telephony.complete, zusätzlich mit origin_domain; from_number ist auf "web" gesetzt.

web.tool#

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

web.turn#

Das Webkanal-Äquivalent von telephony.turn, das Web-Widget-Anrufe und Builder-Mikrofontestanrufe abdeckt. Dieselbe Payload- Struktur, mit origin_domain anstelle von from_number / to_number. Wie telephony.turn erfordert es ein explizites Abonnement — es wird niemals über ein leeres events-Array zugestellt.

Sprachereignisse#

Die Erstellung benutzerdefinierter Stimmen erfolgt asynchron. Mit diesen nicht blockierenden Ereignissen können Sie auf ein endgültiges Ergebnis reagieren, statt den Endpunkt für Klondetails 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"
}

Qualitätsereignisse#

call.graded#

Wird gesendet, wenn ein KI-Bewertungslauf 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"
}

issue.reported#

Wird gesendet, wenn eine Problemmeldung erstellt wird — entweder von einem Benutzer über das Dashboard eingereicht (source: "user") oder automatisch durch die Anrufbewertung (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"
}

Testanrufereignisse#

test-call.completed#

Wird gesendet, wenn ein Testanruflauf einen Endstatus erreicht — completed oder failed, einschließlich Läufen, die beim Start fehlgeschlagen sind und nie einen Anruf erzeugt haben. Nicht blockierend. Nützlich, um Batch-CI-Lä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"
}

Warnungsereignisse#

alert.triggered#

Wird gesendet, wenn eine Warnungsregel mit aktiviertem Kanal An Entwickler-Webhooks senden ihren Schwellenwert überschreitet. Nicht blockierend. Eine Regel wird einmal ausgelöst und berücksichtigt anschließend ihre Abklingzeit, sodass ein anhaltender Verstoß ein Ereignis pro Abklingzeitfenster 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"
}

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

Verwandt#