Webhooks

Gebeurteniscatalogus

Alle webhook-gebeurtenistypen die ThunderPhone verzendt.

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 gewenste gebeurtenistypen bevatten (of leeg zijn om je op alles te abonneren — behalve de gebeurtenissen per beurt telephony.turn / web.turn, die alleen worden geleverd aan endpoints die ze expliciet vermelden).

Deze gebeurtenissen worden via twee leveringsstijlen verzonden:

• Endpointleveringen zijn altijd niet-blokkerende meldingen met herpogingen: reageer met een willekeurige 2xx; de envelop bevat een event_id om op te dedupliceren.
• 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 tooldispatch in webhookmodus tool dispatch. Je reactie bepaalt de live oproep.

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. Leveringen aan endpoints zijn fire-and-forgetmeldingen die worden verzonden voor elke inkomende oproep, ongeacht of het nummer voor een agent of webhook is geconfigureerd. Nummers zonder toegewezen agent ontvangen daarnaast het verzoek voor de blokkerende configuratie 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 wanneer beschikbaar, en de 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 omvat je eigen functietools (geen ingebouwde tools, kennisbanktools, tools voor app-verbindingen 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.

telephony.turn#

Verzonden terwijl een telefonieoproep bezig is, eenmaal voor elke spraakbevattende beurt zodra die plaatsvindt — de uitgesproken voltooiingen van de agent en de getranscribeerde beurten van de beller. Hiermee kun je het livegesprek via gewone webhooks volgen in plaats van te pollen op GET /v1/calls/{call_id}/transcript. Niet-blokkerend.

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

Het webkanaalequivalent van telephony.incoming, verzonden wanneer een sessie van een webwidget of een microfoontestoproep in de builder begint. Leveringen aan endpoints zijn fire-and-forget voor elke websessie. Publiceerbare sleutels in mode="webhook" ontvangen daarnaast het verzoek voor de blokkerende configuratie op de verouderde webhook — dat blokkerende verzoek heeft een andere vorm (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 widgetsessies 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 payloadvorm als telephony.complete, plus origin_domain, waarbij from_number is ingesteld op "web".

web.tool#

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

web.turn#

Het webkanaalequivalent van telephony.turn, voor oproepen via de webwidget en microfoontestoproepen in de builder. Dezelfde payloadvorm, met origin_domain in plaats van from_number / to_number. Net als telephony.turn vereist dit een expliciete inschrijving — het wordt nooit afgeleverd via een lege events-array.

Spraakgebeurtenissen#

Aangepaste spraakcreatie 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"
}

Kwaliteitsgebeurtenissen#

call.graded#

Verzonden wanneer een AI-beoordelingsuitvoering 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"
}

issue.reported#

Verzonden wanneer een probleemrapport wordt gemaakt — 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"
}

Testoproepgebeurtenissen#

test-call.completed#

Verzonden wanneer een testoproepuitvoering een eindstatus bereikt — completed of failed, inclusief uitvoeringen die bij het starten zijn mislukt en nooit een oproep hebben gemaakt. Niet-blokkerend. Handig om batchgewijze CI-uitvoeringen 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"
}

Waarschuwingsgebeurtenissen#

alert.triggered#

Verzonden wanneer een waarschuwingsregel met het kanaal Leveren aan developer-webhooks ingeschakeld de drempel overschrijdt. Niet-blokkerend. Een regel wordt één keer geactiveerd en respecteert daarna de cooldown, dus een aanhoudende overschrijding 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"
}

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

Gerelateerd#