> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# telephony.complete / web.complete
> Niet-blokkerende webhook die wordt verzonden wanneer een oproep eindigt, met transcript, opname-URL en statistieken.
Een voltooiingsgebeurtenis wordt geactiveerd nadat elk gesprek is beëindigd — inkomende telefonie,
uitgaande telefonie, webgesprek of testgesprek (buildersessie met microfoon). Deze is
**niet-blokkerend**: reageer met een willekeurige 2xx.
De gebeurtenis wordt via beide paden afgeleverd:
* **[Webhook-eindpunten](/nl/webhooks/endpoints)** ontvangen
`telephony.complete` (telefoongesprekken) of `web.complete` (webgesprekken en
microfoontestgesprekken in de builder) met de hieronder beschreven stabiele payload,
een `event_id` per aflevering, een time-out van 30 s en
[opnieuw proberen gedurende maximaal 24 h](/nl/webhooks/overview).
* **De [verouderde webhook met één URL](/api-reference/organizations#legacy-single-url-webhook)**
ontvangt één synchrone poging (time-out van 10 s, geen nieuwe pogingen) met een
iets andere payload — zie
[Verschillen in verouderde payloads](#legacy-payload-differences).
## Requestpayload (afleveringen via eindpunten)
```json theme={null}
{
"data": {
"billable_minutes": 1.25,
"billing_total_cents": 8,
"call_id": 987654321,
"direction": "inbound",
"duration_seconds": 54,
"end_reason": "user_hangup",
"end_time": "2026-04-20T18:25:04.822Z",
"from_number": "+14155550199",
"product": "spark",
"recording_url": "https://storage.example.com/…",
"start_time": "2026-04-20T18:24:10.113Z",
"status": "completed",
"to_number": "+15551234567",
"transcripts": [ /* see Transcript format */ ],
"transfer_number": null,
"voice": "john"
},
"event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"type": "telephony.complete"
}
```
| Veld | Type | Beschrijving |
| -------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call_id` | integer | Stabiel voor elke gebeurtenis van dit gesprek |
| `direction` | string | `inbound`, `outbound`, `web`, `test`. Historische payloads kunnen verouderde waarden `mic` of `widget` bevatten |
| `from_number`, `to_number` | string | E.164. `from_number` is letterlijk `"web"` voor webgesprekken en testgesprekken |
| `origin_domain` | string | **Alleen web/test** — de pagina-oorsprong waarop de widget werd gehost (leeg voor microfoonsessies) |
| `start_time`, `end_time` | timestamp | ISO 8601 UTC |
| `duration_seconds` | integer \| null | Afgeleid van start/einde |
| `status` | string | `completed` of `failed` |
| `end_reason` | string | Zie onderstaande tabel |
| `product`, `voice` | string | Agentconfiguratie die tijdens het gesprek van kracht was |
| `transfer_number` | string \| null | Ingesteld wanneer het gesprek is doorverbonden |
| `recording_url` | string \| null | Ondertekende URL met vervaldatum; download deze direct. `null` voor sessies zonder opname |
| `billable_minutes` | number | Gefactureerde minuten, afgerond op het dichtstbijzijnde kwartier (stappen van 15 seconden, minimum 0,25). Gesprekken die direct naar voicemail gaan, kosten in plaats daarvan een vast bedrag van 1¢. |
| `billing_total_cents` | integer | Amerikaanse dollarcenten |
| `transcripts` | array | Transcript per beurt — zie volgende sectie |
### Redenen voor beëindiging
| Waarde | Betekenis |
| ------------------ | ----------------------------------------------------------------------------------- |
| `user_hangup` | Externe partij heeft als eerste opgehangen |
| `ai_hangup` | AI heeft het gesprek bewust beëindigd |
| `ai_transfer` | AI heeft het gesprek doorverbonden; `transfer_number` is ingesteld |
| `ai_warm_transfer` | AI heeft een warme (begeleide) doorverbinding voltooid |
| `voicemail_hangup` | Voicemail is gedetecteerd en het gesprek is beëindigd volgens je `voicemail_action` |
| `max_duration` | Gesprek heeft de maximale gespreksduur bereikt |
| `superseded` | De sessie is vervangen door een nieuwere |
| `unknown` | Reden voor beëindiging kon niet worden vastgesteld |
## Transcriptindeling
Elke invoer in `transcripts` is één gespreksbeurt. Rollen zijn
`user` (spraak van de beller), `model` (spraak van de agent **en** toolaanroepen),
`tool` (toolresultaten) en `system` (oproepgebeurtenissen zoals
taalwisselingen).
```json theme={null}
[
{
"role": "user",
"content_type": "text/plain",
"content": "Hi, I'm calling about my appointment.",
"start_ms": 1200,
"end_ms": 4100,
"audio_url": "https://storage.example.com/…"
},
{
"role": "model",
"content_type": "text/plain",
"content": "Sure, what date works best?",
"start_ms": 4200,
"end_ms": 6100
},
{
"role": "model",
"content_type": "application/json",
"content": {
"tool_call": "search_appointments",
"arguments": { "date": "2026-04-21" }
}
},
{
"role": "tool",
"content_type": "application/json",
"content": {
"tool_name": "search_appointments",
"response": { "available_slots": ["9:00 AM", "2:00 PM"] }
}
}
]
```
| Veld | Type | Beschrijving |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role` | string | `user`, `model`, `tool` of `system` |
| `content_type` | string | `text/plain` voor spraak; `application/json` voor toolaanroepen, toolresultaten en systeemgebeurtenissen |
| `content` | string \| object | Spraaktekst of het hierboven weergegeven gestructureerde object. Toolaanroepen: `{"tool_call": name, "arguments": {…}}`. Toolresultaten: `{"tool_name": name, "response": {…}}` |
| `start_ms`, `end_ms` | integer | Offsets vanaf de start van de oproep, in ms. Aanwezig wanneer audiotiming bekend is |
| `ttfa_ms` | integer | Tijd tot eerste audio voor een `model`-beurt, indien gemeten |
| `audio_url`, `audio_urls` | string / array | Verlopende ondertekende URL's voor de audio van de beurt, wanneer deze per beurt wordt opgenomen |
Gebruik voor de volledig gestructureerde beurtgeschiedenis (met onderbrekingsmarkeringen,
bevestigingsprompts en onbewerkte posities)
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Verschillen in legacy-payloads
De legacy webhook-envelop met één URL is
`{"type": "telephony.complete" | "web.complete", "data": {…}}` zonder
**`event_id`**, en de `data` verschilt van de endpoint-payload:
* De beurtarray staat onder **`history`**, niet onder `transcripts` (hetzelfde
beurtenschema als hierboven).
* De veldenset is het onbewerkte rapport aan het einde van de oproep en kan
aanvullende interne velden bevatten naast de bovenstaande tabel — behandel onbekende
velden als informatief.
* Weboproepen (`direction: "web"`) **laten** `from_number` / `to_number`
**weg** en voegen `origin_domain` toe.
* Microfoontestoproepen in Builder worden op het legacy-pad gerapporteerd als
`telephony.complete` (het endpointsysteem koppelt ze aan `web.complete`).
* **Overdrachtscoördinatie:** wanneer een oproep eindigt in een overdracht, wordt de
legacy webhook synchroon aangeroepen en kan deze
`{"transfer_ready": false}` retourneren om aan te geven dat het overdrachtsdoel nog niet
klaar is. Elke andere respons (of geen legacy webhook) laat de overdracht
doorgaan. Endpoint-leveringen worden hiervoor nooit geraadpleegd.
***
## Voorbeeldhandler
```python Python (FastAPI) theme={null}
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, signature: str) -> bool:
expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
body = await request.body()
if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
raise HTTPException(status_code=401)
event = json.loads(body)
if event["type"] in ("telephony.complete", "web.complete"):
data = event["data"]
# Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
turns = data.get("transcripts") or data.get("history") or []
await persist_call_record(
call_id=data["call_id"],
turns=turns,
recording_url=data.get("recording_url"),
)
if data["end_reason"] in ("ai_transfer", "ai_warm_transfer"):
await notify_team(data.get("transfer_number"), data["call_id"])
return {"ok": True}
```
```javascript Node.js (Express) theme={null}
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
function verify(body, signature) {
const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
return signature &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
app.post(
"/thunderphone-webhook",
express.raw({ type: "application/json" }),
async (req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (["telephony.complete", "web.complete"].includes(event.type)) {
const data = event.data;
// Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
const turns = data.transcripts ?? data.history ?? [];
await persistCallRecord({ ...data, turns });
if (["ai_transfer", "ai_warm_transfer"].includes(data.end_reason)) {
await notifyTeam(data.transfer_number, data.call_id);
}
}
res.json({ ok: true });
},
);
```
***
## Veelvoorkomende toepassingen
Sla het transcript en de opname-URL van elke oproep op naast je
klantgegevens.
Stream transcripties naar een pipeline voor onderwerpmodellering, extractie
van CSAT-signalen of monitoring van het doorverbindingspercentage.
Open oproepen in een QA-tool voor menselijke beoordeling, of voer ze uit
via je eigen evaluatiemodel.
Activeer een menselijke teamgenoot bij doorverbinding / storing.
***
## Gerelateerd
De blokkerende tegenhanger die bij de start van een oproep wordt uitgevoerd.
Andere gebeurtenistypen waarop je je kunt abonneren.
Dezelfde gegevens zijn via REST beschikbaar voor aanvullen / opnieuw afspelen.