> ## 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-pemblokiran yang dikirim saat panggilan berakhir, dengan transkrip, URL rekaman, dan metrik.
Peristiwa penyelesaian dipicu setelah setiap panggilan berakhir — telepon masuk,
telepon keluar, panggilan web, atau panggilan uji (sesi mikrofon builder). Peristiwa ini
**tidak memblokir**: tanggapi dengan 2xx apa pun.
Peristiwa dikirimkan melalui kedua jalur:
* **[Endpoint webhook](/id/webhooks/endpoints)** menerima
`telephony.complete` (panggilan telepon) atau `web.complete` (panggilan web dan
panggilan uji mikrofon builder) dengan payload stabil yang didokumentasikan di bawah,
`event_id` per pengiriman, batas waktu 30 dtk, dan
[percobaan ulang hingga 24 jam](/id/webhooks/overview).
* **[Webhook URL tunggal lama](/api-reference/organizations#legacy-single-url-webhook)**
menerima satu percobaan sinkron (batas waktu 10 dtk, tanpa percobaan ulang) dengan
payload yang sedikit berbeda — lihat
[Perbedaan payload lama](#legacy-payload-differences).
## Payload permintaan (pengiriman 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"
}
```
| Bidang | Tipe | Deskripsi |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `call_id` | integer | Tetap sama di setiap peristiwa untuk panggilan ini |
| `direction` | string | `inbound`, `outbound`, `web`, `test`. Payload historis mungkin berisi nilai lama `mic` atau `widget` |
| `from_number`, `to_number` | string | E.164. `from_number` bernilai literal `"web"` untuk panggilan web dan panggilan uji |
| `origin_domain` | string | **Khusus web/uji** — asal halaman yang menghosting widget (kosong untuk sesi mikrofon) |
| `start_time`, `end_time` | timestamp | ISO 8601 UTC |
| `duration_seconds` | integer \| null | Diturunkan dari waktu mulai/akhir |
| `status` | string | `completed` atau `failed` |
| `end_reason` | string | Lihat tabel di bawah |
| `product`, `voice` | string | Konfigurasi agen yang berlaku saat panggilan berlangsung |
| `transfer_number` | string \| null | Ditetapkan saat panggilan ditransfer |
| `recording_url` | string \| null | URL bertanda tangan yang kedaluwarsa; segera unduh. `null` untuk sesi tanpa rekaman |
| `billable_minutes` | number | Menit yang ditagihkan, dibulatkan ke seperempat menit terdekat (inkremen 15 detik, minimum 0.25). Panggilan yang langsung masuk ke pesan suara ditagihkan tarif tetap 1¢ sebagai gantinya. |
| `billing_total_cents` | integer | Sen USD |
| `transcripts` | array | Transkrip per giliran — lihat bagian berikutnya |
### Alasan berakhir
| Nilai | Arti |
| ------------------ | ---------------------------------------------------------------------------- |
| `user_hangup` | Pihak lawan bicara menutup telepon terlebih dahulu |
| `ai_hangup` | AI mengakhiri panggilan dengan sengaja |
| `ai_transfer` | AI mentransfer panggilan; `transfer_number` ditetapkan |
| `ai_warm_transfer` | AI menyelesaikan transfer hangat (dengan pendampingan) |
| `voicemail_hangup` | Pesan suara terdeteksi dan panggilan diakhiri sesuai `voicemail_action` Anda |
| `max_duration` | Panggilan mencapai batas durasi maksimum |
| `superseded` | Sesi digantikan oleh sesi yang lebih baru |
| `unknown` | Alasan berakhir tidak dapat ditentukan |
## Format transkrip
Setiap entri dalam `transcripts` adalah satu giliran percakapan. Perannya adalah
`user` (ucapan penelepon), `model` (ucapan agen **dan** pemanggilan tool),
`tool` (hasil tool), dan `system` (peristiwa panggilan seperti perpindahan
bahasa).
```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"] }
}
}
]
```
| Kolom | Tipe | Deskripsi |
| ------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role` | string | `user`, `model`, `tool`, atau `system` |
| `content_type` | string | `text/plain` untuk ucapan; `application/json` untuk pemanggilan tool, hasil tool, dan peristiwa sistem |
| `content` | string \| object | Teks ucapan, atau objek terstruktur yang ditampilkan di atas. Pemanggilan tool: `{"tool_call": name, "arguments": {…}}`. Hasil tool: `{"tool_name": name, "response": {…}}` |
| `start_ms`, `end_ms` | integer | Offset dari awal panggilan, dalam ms. Ada saat waktu audio diketahui |
| `ttfa_ms` | integer | Waktu hingga audio pertama untuk giliran `model`, saat diukur |
| `audio_url`, `audio_urls` | string / array | URL bertanda tangan yang kedaluwarsa untuk audio giliran tersebut, saat direkam per giliran |
Untuk riwayat giliran yang sepenuhnya terstruktur (dengan penanda interupsi,
ack-prompt, dan posisi mentah), gunakan
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Perbedaan payload legacy
Envelope webhook URL tunggal legacy adalah
`{"type": "telephony.complete" | "web.complete", "data": {…}}` tanpa
**`event_id`**, dan `data`-nya berbeda dari payload endpoint:
* Array giliran berada di bawah **`history`**, bukan `transcripts` (schema giliran
sama seperti di atas).
* Kumpulan kolomnya adalah laporan mentah akhir panggilan dan dapat mencakup
kolom internal tambahan di luar tabel di atas — perlakukan kolom yang tidak dikenal
sebagai informasi.
* Panggilan web (`direction: "web"`) **tidak menyertakan** `from_number` / `to_number`
dan menambahkan `origin_domain`.
* Panggilan uji mikrofon Builder dilaporkan sebagai `telephony.complete` pada jalur
legacy (sistem endpoint memetakannya ke `web.complete`).
* **Koordinasi transfer:** saat panggilan berakhir dalam transfer, webhook
legacy dipanggil secara sinkron dan dapat menjawab
`{"transfer_ready": false}` untuk menandakan target serah terima belum
siap. Respons lain apa pun (atau tanpa webhook legacy) memungkinkan transfer
dilanjutkan. Pengiriman endpoint tidak pernah digunakan untuk ini.
***
## Contoh handler
```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 });
},
);
```
***
## Kasus penggunaan umum
Simpan transkrip + URL rekaman setiap panggilan bersama catatan
pelanggan Anda.
Alirkan transkrip ke pipeline untuk pemodelan topik, ekstraksi sinyal CSAT,
atau pemantauan tingkat transfer.
Buka panggilan di alat QA untuk ditinjau manusia, atau jalankan melalui
model evaluasi Anda sendiri.
Picu notifikasi kepada rekan tim manusia saat transfer / kegagalan.
***
## Terkait
Versi pemblokiran yang berjalan saat panggilan dimulai.
Jenis event lain yang dapat Anda langgani.
Data yang sama dapat diakses melalui REST untuk backfill / replay.