Gebeurteniscatalogus

Elke webhookbody heeft een veld type waarvan de waarde een van de gebeurtenistypen op deze pagina is. Wanneer je je abonneert op een endpoint, moet de array events de gebeurtenistypen bevatten die je wilt ontvangen (of leeg zijn om je op alles te abonneren). Deze gebeurtenissen worden op twee manieren afgeleverd:

Endpointleveringen zijn altijd niet-blokkerende meldingen met opnieuw proberen: reageer met een willekeurige 2xx; de envelop bevat een event_id voor deduplicatie.
Blokkerende uitwisselingen vinden alleen plaats via de verouderde webhook met één URL: het configuratieverzoek telephony.incoming / web.incoming (nummers in webhookmodus en widgetsleutels, time-out van 10 s) en tool-dispatch in webhookmodus tool-dispatch. Je reactie bepaalt het live gesprek.

De onderstaande voorbeeldpayloads tonen de endpointenvelop in de volgorde waarin deze wordt verzonden (sleutels alfabetisch gesorteerd: data, event_id, type); verouderde leveringen bevatten dezelfde data zonder event_id.

Oproepgebeurtenissen

`telephony.incoming`

Verzonden wanneer een inkomende oproep een van je telefoonnummers bereikt. Endpointleveringen zijn fire-and-forgetmeldingen die voor elke inkomende oproep worden verzonden, ongeacht of het nummer voor een agent of webhook is geconfigureerd. Nummers zonder toegewezen agent ontvangen daarnaast het blokkerende configuratieverzoek op de verouderde webhook — zie telephony.incoming / web.incoming voor het volledige aanvraag-/antwoordschema.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

Verzonden wanneer een inkomende of uitgaande telefonieoproep eindigt. Niet-blokkerend. Bevat het transcript, de opname-URL indien beschikbaar en het factureringsoverzicht. Zie telephony.complete / web.complete voor het payloadschema.

`telephony.tool`

Verzonden nadat een telefonieoproep een functietool aanroept. Niet-blokkerende auditmelding — de tool is al uitgevoerd wanneer deze gebeurtenis wordt afgeleverd; dit betreft je eigen functietools (geen ingebouwde tools, kennisbanktools, app-verbindings- of 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 is het uitgevoerde resultaat: {"status": <http status>, "response": <your endpoint's JSON>} bij succes, of {"status": <status>, "error": "<message>"} bij een fout.

`web.incoming`

Het webkanaalequivalent van telephony.incoming, verzonden wanneer een webwidget-sessie of een microfoontestoproep in de builder start. Endpointleveringen zijn fire-and-for-get voor elke websessie. Publiceerbare sleutels in mode="webhook" ontvangen daarnaast het blokkerende configuratieverzoek op de verouderde webhook — dat blokkerende verzoek heeft een andere structuur (origin_domain, publishable_key_prefix; geen telefoonnummers). Zie 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 is altijd de letterlijke waarde "web". Voor webwidgetsessies in webhookmodus is to_number leeg (het agentnummer van de sessie wordt na configuratie toegewezen); voor microfoontestoproepen in de builder zijn origin_domain en publishable_key_prefix leeg.

`web.complete`

Het webkanaalequivalent van telephony.complete, voor oproepen via de webwidget (direction: "web") en microfoontestoproepen in de builder (direction: "test"). Niet-blokkerend. Dezelfde payloadstructuur als telephony.complete, plus origin_domain, waarbij from_number is ingesteld op "web".

Op de verouderde webhook met één URL worden microfoontestoproepen in de builder van oudsher gerapporteerd als telephony.complete — alleen oproepen met direction: "web" gebruiken daar het type web.complete. Het endpointsysteem koppelt zowel web- als testoproepen aan web.*. Historische payloads kunnen de verouderde waarden widget of mic voor direction bevatten.

`web.tool`

Het webkanaalequivalent van telephony.tool. De data bevat origin_domain in plaats van from_number / to_number.

Spraakgebeurtenissen

Het maken van aangepaste stemmen verloopt asynchroon. Met deze niet-blokkerende gebeurtenissen kun je reageren op een eindresultaat in plaats van de clone-detailendpoint te pollen.

`voice.ready`

Verzonden wanneer een aangepaste stem klaar is met verwerken en aan een agent kan worden toegewezen.

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

Verzonden wanneer de verwerking van een aangepaste stem permanent mislukt.

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

Veld	Type	Beschrijving
`voice.id`	string	Openbare id van de aangepaste stem
`voice.name`	string	Stemwaarde van de agent in de vorm `custom:<public_id>`
`voice.display_name`	string	Naam van de stem voor de organisatie
`voice.language`	string	De enkele taalcode van de clone
`voice.gender`	string	`male`, `female` of een lege tekenreeks
`voice.status`	string	`ready` voor `voice.ready`; `failed` voor `voice.failed`
`voice.failure_reason`	string	Leeg bij succes; details over de verwerkingsfout bij mislukking
`voice.created_at`, `voice.updated_at`	timestamp	ISO 8601-tijdstempels
`reason`	string	Details over de fout; alleen aanwezig bij `voice.failed`

Kwaliteitsgebeurtenissen

`call.graded`

Verzonden wanneer een AI-beoordelingsrun voor een oproep is voltooid. Niet-blokkerend.

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

Veld	Type	Beschrijving
`grade.id`	integer	Beoordelings-id
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` of `no_conversation`
`grade.summary`	string	Samenvatting van één alinea
`grade.detected_issues`	array	Probleemreeksen die door de beoordelaar zijn gevonden
`grade.status`	string	Altijd `completed` — alleen voltooide runs worden verzonden
`grade.grader_model`	string	Welke beoordelaar het resultaat heeft geproduceerd (bijv. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Een oproep kan meer dan één keer worden beoordeeld — een snelle heuristische beoordeling wordt vaak gevolgd door een volledige modelbeoordeling zodra de opname beschikbaar is, en handmatige herbeoordelingen zijn mogelijk. Elke voltooide run verzendt een eigen call.graded-gebeurtenis; beschouw de meest recente graded_at als leidend.

`issue.reported`

Verzonden wanneer een probleemrapport wordt aangemaakt — ofwel ingediend door een gebruiker vanuit het dashboard (source: "user"), of automatisch door oproepbeoordeling (source: "system"). Niet-blokkerend.

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

Veld	Type	Beschrijving
`issue_report.severity`	string	`critical`, `warning` of `info`
`issue_report.status`	string	`open` of `resolved`
`issue_report.source`	string	`user` (ingediend vanuit het dashboard) of `system` (aangemaakt door beoordeling)

Het herbeoordelen van een oproep bouwt de door het systeem gegenereerde probleemrapporten opnieuw op, waardoor issue.reported opnieuw wordt verzonden voor de opnieuw aangemaakte rapporten. Dedupliceer op call_id + title als je slechts één melding per onderliggend probleem wilt.

Testoproepgebeurtenissen

`test-call.completed`

Verzonden wanneer een testoproep-run een eindstatus bereikt — completed of failed, inclusief runs die bij het starten zijn mislukt en nooit een oproep hebben geproduceerd. Niet-blokkerend. Nuttig om batchgewijze CI-runs te koppelen aan je chat-/meldingssystemen.

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

Veld	Type	Beschrijving
`test_call_run.target_type`	string	`agent` of `phone_number`
`test_call_run.target_id`	integer	De agent-id of telefoonnummer-id waarop de run was gericht, overeenkomstig `target_type`
`test_call_run.status`	string	`completed` of `failed`
`test_call_run.call_id`	integer \| null	`null` wanneer de run mislukte voordat een oproep werd geplaatst
`test_call_run.error_message`	string	Leeg bij succes

Waarschuwingsgebeurtenissen

`alert.triggered`

Verzonden wanneer een waarschuwingsregel met het kanaal Bezorgen bij developer-webhooks ingeschakeld de drempel overschrijdt. Niet-blokkerend. Een regel wordt eenmaal geactiveerd en respecteert vervolgens de cooldown, dus een aanhoudende overtreding produceert één gebeurtenis per cooldownvenster.

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

Veld	Type	Beschrijving
`event_id` (in `data`)	UUID	De activerings-ID van de waarschuwing — verschillend van de `event_id` voor bezorging in de envelop
`rule_id`, `rule_name`	UUID, string	De regel die werd geactiveerd
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume` of `suite_regression`
`comparator`	string	`lt`, `lte`, `gt` of `gte`
`metric_value`	number	De waarde van de metriek binnen het venster toen de regel werd geactiveerd
`threshold`	number	De geconfigureerde drempel
`window_hours`	integer	Voortschrijdend evaluatievenster
`fired_at`	timestamp

Zie de gids voor waarschuwingen voor het maken van regels, metriekwaarden, cooldowns en de e-mail- / Slack-kanalen.

Gerelateerd

telephony.incoming / web.incoming

De blokkerende payload voor inkomende oproepen waarop je moet reageren.

telephony.complete / web.complete

Transcript en metriekwaarden na de oproep.

Webhook-eindpunten

Abonneer een URL op een subset van deze gebeurtenissen.

Functietools

Hoe telephony.tool / web.tool-gebeurtenissen worden gegenereerd.

Webhooks

Function Tools

Oproepgebeurtenissen

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Spraakgebeurtenissen

`voice.ready`

`voice.failed`

Kwaliteitsgebeurtenissen

`call.graded`

`issue.reported`

Testoproepgebeurtenissen

`test-call.completed`

Waarschuwingsgebeurtenissen

`alert.triggered`

Gerelateerd

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-eindpunten

Functietools

​Oproepgebeurtenissen

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Spraakgebeurtenissen

​voice.ready

​voice.failed

​Kwaliteitsgebeurtenissen

​call.graded

​issue.reported

​Testoproepgebeurtenissen

​test-call.completed

​Waarschuwingsgebeurtenissen

​alert.triggered

​Gerelateerd

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-eindpunten

Functietools

Oproepgebeurtenissen

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Spraakgebeurtenissen

`voice.ready`

`voice.failed`

Kwaliteitsgebeurtenissen

`call.graded`

`issue.reported`

Testoproepgebeurtenissen

`test-call.completed`

Waarschuwingsgebeurtenissen

`alert.triggered`

Gerelateerd