Ereigniskatalog

Alle Webhook-Ereignistypen, die ThunderPhone ausgibt.

Jeder Webhook-Body enthält ein Feld type, dessen Wert einem der Ereignistypen auf dieser Seite entspricht. Wenn Sie einen Endpunkt abonnieren, muss das Array events die gewünschten Ereignistypen enthalten (oder leer sein, um alles zu abonnieren — ausgenommen die Ereignisse pro Gesprächszug telephony.turn / web.turn, die nur an Endpunkte zugestellt werden, die sie ausdrücklich nennen).

Diese Ereignisse werden in zwei Zustellungsarten übertragen:

• Endpoint-Zustellungen sind immer nicht blockierende Benachrichtigungen mit Wiederholungsversuchen: Antworten Sie mit einem beliebigen 2xx; der Umschlag enthält eine event_id zur Deduplizierung.
• Blockierende Austausche erfolgen nur über den Legacy-Webhook mit einer einzelnen URL: die Konfigurationsanfrage telephony.incoming / web.incoming (Nummern im Webhook-Modus: 13 s einschließlich eines Wiederholungsversuchs; Widget-Schlüssel im Webhook-Modus: 10 s) und die Tool-Weiterleitung im Webhook-Modus. Ihre Antwort gestaltet den Live-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. Endpunktzustellungen sind Fire-and-forget-Benachrichtigungen für jeden eingehenden Anruf, 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 Transkript, die Aufzeichnungs-URL, sofern verfügbar, sowie eine Abrechnungsübersicht. Siehe telephony.complete / web.complete für das Payload-Schema.

telephony.tool#

Wird gesendet, nachdem ein Telefonanruf ein Funktions-Tool aufruft. Nicht blockierende Audit-Benachrichtigung — das Tool wurde bereits ausgeführt, wenn dieses Ereignis zugestellt wird; es umfasst Ihre eigenen Funktions-Tools sowie das integrierte Tool send_sms (nicht andere integrierte, Wissensdatenbank-, App-Verbindungs- oder MCP-Tools). Für send_sms werden sowohl arguments.to als auch arguments.body als [REDACTED] angezeigt. Auch Abschluss-Transkripte schwärzen diese Werte; rufen Sie Inhalt und Empfänger über die organisationsbezogene SMS-Ressource anhand der message_id der Antwort ab.

{
  "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 Telefonanrufs gesendet, der läuft, einmal für jeden sprachhaltigen Turn, sobald er auftritt — die gesprochenen Antworten des Agenten und die transkribierten Turns des Anrufers. Ermöglicht Ihnen, die Live-Unterhaltung über einfache Webhooks zu verfolgen, anstatt 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, gesendet, wenn eine Web-Widget-Sitzung oder ein Builder-Mikrofontestanruf beginnt. Endpunktzustellungen erfolgen für jede Websitzung als 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. Gleiche Payload-Struktur wie telephony.complete, zusätzlich mit origin_domain, wobei from_number auf "web" gesetzt ist.

web.tool#

Das Webkanal-Äquivalent von telephony.tool. 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. Gleiche 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.

call.transfer_completed#

Wird einmal pro Anruf mit dem endgültigen Ergebnis einer Anrufweiterleitung gesendet: einer kalten Weiterleitung oder der menschlichen Verbindung, die bei einer warmen Weiterleitung verbleibt, nachdem der Agent ausscheidet. Nicht blockierend und nur an Endpunkte zugestellt (nie an den Legacy- Webhook mit einer einzelnen URL). Trifft nach telephony.complete des Anrufs ein: wenn der Anbieter den Anruf übernimmt oder die Weiterleitung fehlschlägt oder, wenn ThunderPhone den Anruf verbunden hat, sobald die Verbindung endet.

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

Dieselben Werte befinden sich im Anrufobjekt als transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds und transfer_bridge_total_cents. event_id ist bei jeder Zustellung für einen Anruf gleich, sodass eine wiederholte Meldung kein zweites Ereignis erzeugt.

SMS-Ereignisse#

SMS-Ereignisse beschreiben Nachrichten, die über das verbundene Twilio- oder Telnyx-Konto der Organisation gesendet werden. Der Nachrichtentext wird ausgelassen und to wird geschwärzt. Rufen Sie die organisationsbezogene Nachricht über GET /v1/sms/{message_id} ab, wenn ihr Inhalt oder Empfänger benötigt wird.

sms.sent#

Wird gesendet, wenn der Mobilfunkanbieter des Kunden eine ausgehende SMS-Anfrage akzeptiert. Dies ist keine Zustellbestätigung des Endgeräts.

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

Wird nach einer dauerhaften Ablehnung durch den Mobilfunkanbieter, nach Ausschöpfung vorübergehender Wiederholungsversuche oder bei einem endgültig unbekannten Ergebnis gesendet. error_code ist ein stabiler ThunderPhone-Code, und error_message nennt die erforderliche Kundenaktion, sofern verfügbar. status: "unknown" bedeutet, dass der Mobilfunkanbieter die SMS möglicherweise akzeptiert hat; gleichen Sie dies im Protokoll des Mobilfunkanbieters ab, da ThunderPhone sie nicht automatisch erneut sendet.

sms.received#

Für die Unterstützung eingehender SMS reserviert. In der aktuellen Version werden keine sms.received-Ereignisse ausgegeben. Die Konfiguration eingehender Webhooks des Mobilfunkanbieters und die Signaturprüfung werden separat bereitgestellt.

Sprachereignisse#

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

voice.ready und voice.failed werden nur an einen organisationsweiten Endpunkt mit events: [] zugestellt. Sie können nicht als explizite Ereignisfilter ausgewählt werden.

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 eine KI-Bewertung 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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Wird gesendet, wenn die Extraktion strukturierter Daten erfolgreich abgeschlossen wurde, einschließlich eines späteren Wiederholungsversuchs nach telephony.complete / web.complete oder einer manuellen erneuten Ausführung über POST /v1/calls/{call_id}/extract. Nicht blockierend.

In einem blockierenden Extraktionsmodus wartet das Abschlussereignis normalerweise nicht länger als das Extraktionsbudget von 75 Sekunden. Wenn der Extraktions-Worker-Prozess verloren geht, gibt der Produktionsabschluss-Drain (alle fünf Minuten) einen Abschluss frei, dessen blocking_deadline_at abgelaufen ist, bevor ein weiterer Extraktionsversuch gestartet wird. Ein späterer Erfolg wird separat als dieses Ereignis zugestellt.

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

campaign.completed#

Wird einmal gesendet, wenn eine Kampagne von running zu completed wechselt, unabhängig davon, ob ihr Zeitplan endete oder alle Kontakte Endzustände erreicht haben. Wiederholungsversuche des Runners senden kein weiteres Ereignis. Dieses Lebenszyklusereignis auf Organisationsebene wird nur an Endpunkte mit Organisationsbereich zugestellt, nicht an Endpunkte mit Agentenbereich. Nicht blockierend.

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

Die vier Ergebnisanzahlen sind disjunkt und ergeben zusammen contacts_total: completed enthält erfolgreiche Kontakte; no_answer enthält endgültig fehlgeschlagene oder ausgeschöpfte Kontakte, deren finales Ergebnis keine Antwort war; failed enthält alle anderen endgültig fehlgeschlagenen oder ausgeschöpften Kontakte; und remaining enthält ausstehende, geplante oder aktuell angerufene Kontakte. Ein Kontakt, der auf einen Wiederholungsversuch wartet, ist remaining, selbst wenn sein jüngster Versuch keine Antwort ergab. Laufende Anrufe werden vor dem einmaligen Abschluss-Snapshot abgeglichen. started_at ist der konfigurierte Kampagnenstart oder die Erstellungszeit der Kampagne, wenn kein Start konfiguriert wurde.

issue.reported#

Wird gesendet, wenn ein Problembericht erstellt wird — entweder von einem Benutzer im 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"
}

issue.escalated#

Wird gesendet, wenn ein Problemmuster zur Überprüfung durch Mitarbeitende an ThunderPhone gesendet wird: nach An ThunderPhone melden oder wenn Mit KI beheben keine kundenseitige Behebung bestätigen kann und das Problem automatisch weiterleitet. Nur organisationsweite Endpunkte erhalten dieses Ereignis.

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

Dies ist eine Benachrichtigung, nicht das Nachweispaket. Verwenden Sie cluster_id, um sie mit dem Problemmuster zu korrelieren. Siehe An ThunderPhone melden.

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 zum Verbinden von Batch-CI-Durchläufen mit Ihren Chat-/Benachrichtigungssystemen.

{
  "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 dann ihre Abklingzeit. Daher erzeugt eine anhaltende Überschreitung 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"
}

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

Migrationsereignisse#

migration.call.complete#

Wird gesendet, wenn ein über POST /v1/migrations/{id}/calls initiierter Anruf endet, unabhängig davon, welche Plattform ihn entgegengenommen hat. Nicht blockierend. Es trifft bis zu etwa 5 Minuten nach Ende des Anrufs ein. data enthält jedes Feld von telephony.complete sowie einen migration-Block. Ein von ThunderPhone initiierter Anruf sendet wie gewohnt auch telephony.complete mit derselben call_id. Ein Anruf auf der anderen Plattform, der nach 2 Stunden noch nicht beendet ist oder dessen Migration vorher abgeschlossen wurde oder ihren Schlüssel verloren hat, wird mit status: "unknown" und ohne Transkript gesendet.

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

Für einen vendor-Anruf verfügt ThunderPhone über keine Abrechnungs- oder Extraktionsdaten: billable_minutes, billing_total_cents und extracted_data sind null, product und voice sind leer, recording_mode ist vendor und recording_url ist der Link der anderen Plattform, falls sie einen bereitgestellt hat.

migration.rollback#

Wird gesendet, wenn die schrittweise Umstellung einer Migration alle Anrufe automatisch zurück auf die andere Plattform verschiebt: 3 Anrufe konnten innerhalb von 15 Minuten keine Verbindung zu ThunderPhone herstellen, 2 an ThunderPhone gesendete Anrufe endeten, bevor der Agent antwortete, oder ThunderPhones Ergebnisquote bei Aufgaben fiel um mehr als die konfigurierte Differenz unter die der anderen Plattform. Blockiert nicht, einmal pro Rollback. Danach beträgt ThunderPhones Anteil 0 % und die Migration wird pausiert, bis jemand sie auf dem Tab Migration des Agenten fortsetzt. Die Nutzdaten enthalten keine Telefonnummern, Transkripte oder Anruf-IDs.

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

Verwandte Inhalte#