> ## 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
> Webhook non bloccante inviato al termine di una chiamata, con trascrizione, URL della registrazione e metriche.
Un evento di completamento viene attivato al termine di ogni chiamata: telefonia in entrata,
telefonia in uscita, chiamata web o chiamata di test (sessione microfono del builder). È
**non bloccante**: rispondi con un qualsiasi codice 2xx.
L'evento viene recapitato tramite entrambi i percorsi:
* Gli **[endpoint webhook](/it/webhooks/endpoints)** ricevono
`telephony.complete` (chiamate telefoniche) o `web.complete` (chiamate web e
chiamate di test con microfono del builder) con il payload stabile documentato di seguito,
un `event_id` per ogni recapito, un timeout di 30 s e
[tentativi fino a 24 h](/it/webhooks/overview).
* **Il [webhook legacy a URL singolo](/api-reference/organizations#legacy-single-url-webhook)**
riceve un unico tentativo sincrono (timeout di 10 s, nessun tentativo aggiuntivo) con un
payload leggermente diverso — consulta
[Differenze del payload legacy](#legacy-payload-differences).
## Payload della richiesta (recapiti agli endpoint)
```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"
}
```
| Campo | Tipo | Descrizione |
| -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call_id` | integer | Stabile in ogni evento relativo a questa chiamata |
| `direction` | string | `inbound`, `outbound`, `web`, `test`. I payload storici possono contenere i valori legacy `mic` o `widget` |
| `from_number`, `to_number` | string | E.164. `from_number` è il valore letterale `"web"` per le chiamate web e di test |
| `origin_domain` | string | **Solo web/test** — l'origine della pagina che ospita il widget (vuota per le sessioni microfono) |
| `start_time`, `end_time` | timestamp | ISO 8601 UTC |
| `duration_seconds` | integer \| null | Derivato dall'inizio/fine |
| `status` | string | `completed` o `failed` |
| `end_reason` | string | Consulta la tabella seguente |
| `product`, `voice` | string | Configurazione dell'agente attiva al momento della chiamata |
| `transfer_number` | string \| null | Impostato quando la chiamata è stata trasferita |
| `recording_url` | string \| null | URL firmato con scadenza; scaricalo tempestivamente. `null` per le sessioni senza registrazione |
| `billable_minutes` | number | Minuti fatturati, arrotondati al quarto di minuto più vicino (incrementi di 15 secondi, minimo 0,25). Le chiamate che arrivano direttamente alla segreteria telefonica vengono invece fatturate a una tariffa fissa di 1¢. |
| `billing_total_cents` | integer | Centesimi USD |
| `transcripts` | array | Trascrizione per turno — consulta la sezione successiva |
### Motivi di termine
| Valore | Significato |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `user_hangup` | La controparte ha riagganciato per prima |
| `ai_hangup` | L'AI ha terminato deliberatamente la chiamata |
| `ai_transfer` | L'AI ha trasferito la chiamata; `transfer_number` è impostato |
| `ai_warm_transfer` | L'AI ha completato un trasferimento assistito (con consultazione) |
| `voicemail_hangup` | È stata rilevata la segreteria telefonica e la chiamata è terminata secondo `voicemail_action` |
| `max_duration` | La chiamata ha raggiunto il limite massimo di durata |
| `superseded` | La sessione è stata sostituita da una più recente |
| `unknown` | Non è stato possibile determinare il motivo di termine |
## Formato della trascrizione
Ogni voce in `transcripts` corrisponde a un turno conversazionale. I ruoli sono
`user` (parlato del chiamante), `model` (parlato dell'agente **e** chiamate agli strumenti),
`tool` (risultati degli strumenti) e `system` (eventi della chiamata come cambi
di lingua).
```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"] }
}
}
]
```
| Campo | Tipo | Descrizione |
| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role` | string | `user`, `model`, `tool` o `system` |
| `content_type` | string | `text/plain` per il parlato; `application/json` per chiamate agli strumenti, risultati degli strumenti ed eventi di sistema |
| `content` | string \| object | Testo parlato oppure l'oggetto strutturato mostrato sopra. Chiamate agli strumenti: `{"tool_call": name, "arguments": {…}}`. Risultati degli strumenti: `{"tool_name": name, "response": {…}}` |
| `start_ms`, `end_ms` | integer | Offset dall'inizio della chiamata, in ms. Presenti quando è nota la temporizzazione dell'audio |
| `ttfa_ms` | integer | Tempo al primo audio per un turno `model`, quando misurato |
| `audio_url`, `audio_urls` | string / array | URL firmati con scadenza per l'audio del turno, quando registrato per singolo turno |
Per la cronologia dei turni completamente strutturata (con indicatori di interruzione,
prompt di conferma e posizioni grezze), usa
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Differenze del payload legacy
L'envelope webhook legacy a URL singolo è
`{"type": "telephony.complete" | "web.complete", "data": {…}}`, senza
**`event_id`**, e il relativo `data` differisce dal payload dell'endpoint:
* L'array dei turni si trova in **`history`**, non in `transcripts` (stesso schema
dei turni riportato sopra).
* L'insieme di campi è il report grezzo di fine chiamata e può includere
campi interni aggiuntivi oltre a quelli della tabella sopra — considera i campi
sconosciuti come informativi.
* Le chiamate web (`direction: "web"`) **omettono** `from_number` / `to_number`
e aggiungono `origin_domain`.
* Le chiamate di test del microfono nel Builder vengono riportate come `telephony.complete` nel
percorso legacy (il sistema dell'endpoint le mappa a `web.complete`).
* **Coordinamento del trasferimento:** quando una chiamata termina con un trasferimento, il
webhook legacy viene chiamato in modo sincrono e può rispondere
`{"transfer_ready": false}` per segnalare che la destinazione del passaggio di chiamata non è
pronta. Qualsiasi altra risposta (o l'assenza di un webhook legacy) consente al trasferimento
di procedere. Le consegne all'endpoint non vengono mai consultate per questo.
***
## Gestore di esempio
```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 });
},
);
```
***
## Casi d'uso comuni
Archivia la trascrizione e l'URL della registrazione di ogni chiamata insieme ai
record dei clienti.
Invia le trascrizioni a una pipeline per la modellazione degli argomenti, l'estrazione
di segnali CSAT o il monitoraggio del tasso di trasferimento.
Apri le chiamate in uno strumento QA per la revisione umana oppure elaborale con
il tuo modello di valutazione.
Avvisa un membro del team umano in caso di trasferimento o errore.
***
## Correlati
La controparte bloccante che viene eseguita all'avvio della chiamata.
Altri tipi di eventi a cui puoi iscriverti.
Gli stessi dati accessibili tramite REST per il riempimento storico o il replay.