Open in
telephony.complete / web.complete
Webhook isiyozuia inayotumwa simu inapomalizika, ikiwa na nakala ya mazungumzo, URL ya rekodi, na vipimo.
Tukio la ukamilishaji hutokea baada ya kila simu kuisha — simu za ndani, simu za nje, simu za wavuti, au simu za majaribio (kipindi cha maikrofoni cha builder). Ni lisilozuia: jibu kwa 2xx yoyote.
Tukio huwasilishwa kwenye njia zote mbili:
- Ncha za webhook hupokea
telephony.complete(simu za simu) auweb.complete(simu za wavuti na simu za majaribio ya maikrofoni ya builder) zikiwa na payload thabiti iliyoelezwa hapa chini,event_idkwa kila uwasilishaji, muda wa kuisha wa sekunde 30, na majaribio upya kwa hadi saa 24. - Webhook ya zamani ya URL moja hupokea jaribio moja la usawazishaji (muda wa kuisha wa sekunde 10, bila majaribio upya) lenye payload tofauti kidogo — tazama Tofauti za payload ya zamani.
Payload ya ombi (utafikishaji wa endpoint)
{
"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",
"extracted_data": {
"status": "completed",
"fields": {
"customer_name": "Alex Morgan",
"appointment_date": "2026-04-23"
},
"evidence": {
"customer_name": {
"quote": "My name is Alex Morgan",
"speaker_role": "caller",
"turn_index": 4
},
"appointment_date": {
"quote": "April 23 works for me",
"speaker_role": "caller",
"turn_index": 7
}
},
"verification": "verified",
"field_reasons": {},
"schema_version": "92850758e231a3c95a..."
},
"from_number": "+14155550199",
"product": "spark",
"recording_stopped_at": null,
"recording_stopped_reason": null,
"recording_url": "https://storage.example.com/…",
"start_time": "2026-04-20T18:24:10.113Z",
"status": "completed",
"summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23. The agent read the appointment back and Alex asked for a reminder text the day before.",
"to_number": "+15551234567",
"transcripts": [ /* see Transcript format */ ],
"transfer_number": null,
"unresolved_variables": ["campaign_owner"],
"variables": {"campaign_name": "Spring renewals"},
"voice": "john"
},
"event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"type": "telephony.complete"
}| Sehemu | Aina | Maelezo |
|---|---|---|
call_id | integer | Thabiti katika kila tukio la simu hii |
agent_id | integer | null | Ejenti aliyeshughulikia simu, ikiwa mmoja aliteuliwa |
agent_name | string | null | Ejenti aliyeshughulikia simu, ikiwa mmoja aliteuliwa |
direction | string | inbound, outbound, web, test. Payload za kihistoria zinaweza kuwa na thamani za zamani za mic au widget |
from_number, to_number | string | E.164. from_number ni "web" halisi kwa simu za wavuti na simu za majaribio |
origin_domain | string | Kwa wavuti/majaribio pekee — chanzo cha ukurasa kilichopangisha wijeti (tupu kwa vipindi vya mic) |
start_time, end_time | timestamp | ISO 8601 UTC |
duration_seconds | integer | null | Hupatikana kutoka mwanzo/mwisho |
status | string | completed au failed |
end_reason | string | Tazama jedwali hapa chini |
answered_by | string | null | Simu za kutoka pekee (haipo vinginevyo): aliyejibu, human, voicemail, screener (msaidizi wa kuchuja simu), ivr (menyu ya simu) au unknown. null wakati hakuna aliyejibu, na daima null katika matukio ya migration.call.complete kwa simu za kutoka zilizoshughulikiwa na jukwaa unalohama kutoka. Thamani sawa na objekti ya simu |
product, voice | string | Usanidi wa ejenti uliokuwa ukitumika wakati wa simu |
variables | object | Vigeu vya ingizo vilivyonakiliwa wakati simu ilipoanza |
unresolved_variables | array | Majina ya vigeu vinavyorejelewa na usanidi wa simu lakini havikutolewa wakati simu ilipoanza |
transfer_number | string | null | Huandaliwa simu ilipohamishwa |
scheduled_send_id | string | Kwenye simu iliyowekwa na utumaji ulioratibiwa pekee: kitambulisho cha utumaji huo. Haipo kwenye kila simu nyingine |
recording_url | string | null | URL iliyotiwa sahihi inayokwisha muda; pakua haraka. null wakati hakuna rekodi inayopatikana |
recording_stopped_at | timestamp | null | Wakati rekodi ilisimamishwa kabla simu haijaisha; hakuna chochote baada ya muda huu kilicho kwenye rekodi. null wakati rekodi iliendelea hadi mwisho wa simu au simu haikurekodiwa |
recording_stopped_reason | string | null | Kwa nini rekodi ilisimamishwa mapema. warm_transfer: husimama kabla tu ya uhamisho wa moja kwa moja kupiga simu kwa lengwa, na hubaki imezimwa hata uhamisho ukishindwa na mpigaji akirudi kwa ejenti. Chukulia thamani nyingine kama za taarifa; zaidi zinaweza kuongezwa. null wakati recording_stopped_at ni null |
billable_minutes | number | Dakika zinazotozwa, zikizungushwa hadi robo dakika iliyo karibu zaidi (nyongeza za sekunde 15, kiwango cha chini 0.25). Simu zinazoenda moja kwa moja kwenye voicemail bado huripoti dakika zao halisi zilizopimwa hapa, lakini malipo yanawekewa kikomo cha dakika moja kwa kiwango cha mpango. |
billing_total_cents | integer | null | Senti za USD. null wakati billing_pending ni true |
billing_pending | boolean | Hupo tu, kama true, kwenye simu iliyopimwa ambayo malipo yake bado hayajakamilishwa: simu iliyopimwa hutozwa dakika chache baada ya kuisha, matumizi yake yanapopokelewa, kwa hivyo billable_minutes na billing_total_cents ni null hapa na malipo huwasili katika call.billed. Haipo kwenye kila simu nyingine |
transcripts | array | Ingizo za transkripti kwa kila zamu; zinaweza kuwa tupu transkripti isipopatikana |
summary | string | null | Muhtasari wa baada ya simu kwa lugha ya kawaida (sentensi mbili hadi nne za matini, zisizozidi vibambo 2,000, zilizoandikwa katika summary_language ya ejenti, au lugha ya muhtasari ya shirika, au lugha ya simu: lugha ya msingi ya ejenti isipokuwa simu ilibadilisha lugha hiyo) wakati ejenti amewasha Tengeneza muhtasari wa simu chini ya Data ya kukusanya katika kijenzi cha ejenti (call_summary_enabled kwenye Ejenti) na utengenezaji umefaulu; null vinginevyo, ikiwemo simu fupi mno kufupishwa, simu zisizo na transkripti, na ejenti ambao kurekodi kumezimwa. Muhtasari hutengenezwa katika hatua ileile ya baada ya simu kama utoaji wa data, kwa hivyo mpangilio wa Subiri data iliyotolewa kabla ya kutuma webhook ya simu iliyokamilika (extraction_blocks_completion) huamua kama tukio hili linau-subiri: katika hali ya kusubiri, muhtasari huwa tayari kabla ya tukio hili kutumwa (muhtasari wenyewe hupata hadi sekunde 30 ndani ya bajeti ya sekunde 75 ya hatua); tukio lisiposubiri (never, au uhamisho au kurudi kwenye kituo chako cha mawasiliano chini ya except_transfers) sehemu hii ni null na muhtasari hautumwi tena katika call.data_extracted, kwa hivyo usome baadaye kutoka summary kwenye objekti ya Simu. Pia unapatikana kwenye ukurasa wa simu katika dashibodi |
extracted_data | object | null | Matokeo ya utoaji wa data yaliyopangiliwa yenye status, fields, evidence, verification, field_reasons, na schema_version. Kila sehemu isiyo null ina nukuu kamili iliyokaguliwa kimuundo (isiyozidi vibambo 1,000), pamoja na jukumu la msemaji na faharasa ya zamu; nukuu ndefu zinazorejeshwa na modeli hukataliwa badala ya kufupishwa. Ushahidi ni null wakati sehemu ni null. verified inamaanisha kila pendekezo lilipokea uamuzi mmoja huru halali. unavailable pia inajumuisha matokeo ya kihalalishi yenye hitilafu au yasiyokamilika; maamuzi halali ya sehemu bado hutumika, huku mapendekezo yasiyo na uamuzi mmoja halali yakiwekwa null. status ni completed, failed, exhausted, skipped, au skipped_recording_disabled; null wakati ejenti hakuwa na sehemu za utoaji wa data |
steps_trace | array | Kwenye simu ambazo ejenti wake ana hatua au makabidhiano pekee. Mpangilio ambao simu ilipitia: kila ingizo lina t_ms (milisekunde tangu simu ianze), agent (ufunguo wa ejenti, a pamoja na kitambulisho chake), step (kitambulisho cha hatua, au null kwenye makabidhiano kwa ejenti asiye na hatua) na via (start, model, condition, on_enter au handoff). Huhifadhi vitambulisho na nyakati pekee, kwa hivyo huhifadhiwa hata kurekodi kunapozimwa |
collected_values | object | Kwenye simu ambazo ejenti wake ana hatua au makabidhiano pekee. Thamani ambazo ejenti alikusanya katika hatua zake, zikiwa zimefungwa kwa jina la sehemu ya kukusanya, pamoja na <tool>_result kwa matokeo ya on_enter_tool ya kila hatua. Huondolewa wakati maudhui ya simu hayahifadhiwi (kurekodi kumezimwa) |
Sababu za kumaliza
| Thamani | Maana |
|---|---|
user_hangup | Mhusika wa mbali alikata simu kwanza |
ai_hangup | AI ilimaliza simu kimakusudi |
ai_transfer | AI ilihamisha simu; transfer_number imewekwa |
ai_warm_transfer | AI ilikamilisha uhamisho wa joto (wenye kuhudhuriwa) |
returned_to_platform | AI ilirudisha simu kwenye kituo chako cha mawasiliano: ilikata simu, ikiwa na vichwa vya ingizo la urejeshaji kwenye SIP BYE iwapo vipo |
voicemail_hangup | Ujumbe wa sauti uligunduliwa na simu ilimalizika kulingana na voicemail_action yako |
max_duration | Simu ilifikia kikomo cha juu cha muda: kikomo cha ejenti au cha simu yenyewe, au kikomo cha jukwaa cha saa 6. Simu ambayo AI au mpigaji anaimaliza baada ya onyo la kikomo cha muda hubaki na ai_hangup au user_hangup |
superseded | Kipindi kilibadilishwa na kingine kipya |
inbound_config_webhook_failed | Simu inayoingia kwenye nambari katika hali ya webhook: webhook ya usanidi haikurejesha usanidi unaoweza kutumika, hivyo simu ilimalizwa kabla ejenti hajajibu. status ni failed na simu haitozwi |
outbound_queue_timeout | Simu iliyopangwa foleni ilisubiri dakika 10 bila nafasi ya kupiga. status ni failed, hakuna kilichopigwa, na simu haitozwi |
outbound_queue_canceled | Ulighairi simu iliyopangwa foleni kabla haijapigwa. status ni failed, na simu haitozwi |
unknown | Sababu ya kumalizika haikuweza kubainishwa |
Muundo wa transkripti
Kila ingizo katika transcripts ni zamu moja ya mazungumzo. Majukumu ni
user (usemi wa mpigaji simu), model (usemi wa ejenti na miito ya zana),
tool (matokeo ya zana), na system (matukio ya simu kama vile kubadilisha
lugha).
[
{
"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"] }
}
}
]| Sehemu | Aina | Maelezo |
|---|---|---|
role | string | user, model, tool, au system |
content_type | string | text/plain kwa usemi; application/json kwa miito ya zana, matokeo ya zana na matukio ya mfumo |
content | string | object | Maandishi ya usemi, au kitu kilichopangiliwa kinachoonyeshwa hapo juu. Miito ya zana: {"tool_call": name, "arguments": {…}}. Matokeo ya zana: {"tool_name": name, "response": {…}} |
start_ms, end_ms | integer | Vipimo vya muda kutoka mwanzo wa simu, ms. Huwepo wakati muda wa sauti unajulikana |
ttfa_ms | integer | Muda hadi sauti ya kwanza kwa zamu ya model, unapopimwa |
audio_url, audio_urls | string / array | URL zilizotiwa sahihi zenye muda wa matumizi kwa sauti ya zamu, inaporekodiwa kwa kila zamu |
Kwa historia ya zamu iliyopangiliwa kikamilifu (yenye alama za kukatiza,
vichocheo vya uthibitisho, na nafasi ghafi), tumia
GET /v1/calls/{call_id}/history.
Tofauti za payload ya urithi
Bahasha ya webhook ya urithi yenye URL moja ni
{"type": "telephony.complete" | "web.complete", "data": {…}} bila
event_id, na data yake hutofautiana na payload ya endpoint:
Payload ya ukamilishaji ya urithi pia ina agent_id na agent_name.
- Mkusanyiko wa zamu uko chini ya
history, sitranscripts(schema ya zamu ni sawa na iliyo hapo juu). - Seti ya sehemu ni ripoti ghafi ya mwisho wa simu na inaweza kujumuisha sehemu za ziada za ndani zaidi ya jedwali lililo hapo juu — chukulia sehemu zisizojulikana kama za taarifa.
- Simu za wavuti (
direction: "web") hazijumuishifrom_number/to_numberna huongezaorigin_domain. - Simu za majaribio ya maikrofoni ya Builder huripotiwa kama
telephony.completekwenye njia ya urithi (mfumo wa endpoint huzibadilisha kuwaweb.complete). - Uratibu wa uhamisho: simu inapomalizika kwa uhamisho, webhook ya urithi
huitwa kwa usawazishaji na inaweza kujibu
{"transfer_ready": false}kuashiria kuwa lengwa la uhamisho haliko tayari. Jibu lingine lolote (au kutokuwepo kwa webhook ya urithi) huruhusu uhamisho kuendelea. Uwasilishaji wa endpoint hauzingatiwi kamwe kwa hili.
Kishughulikiaji wa mfano
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}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 });
},
);Matumizi ya kawaida
Hifadhi transkripti ya kila simu na URL ya rekodi pamoja na rekodi za wateja wako.
Tuma transkripti kwa mtiririko wa uchakataji kwa ajili ya uundaji wa mada, uchimbaji wa ishara za CSAT, au ufuatiliaji wa kiwango cha uhamisho.
Fungua simu katika zana ya QA kwa ukaguzi wa kibinadamu, au zipitishe kwenye modeli yako mwenyewe ya tathmini.
Mjulishe mwanatimu wa kibinadamu inapohamishwa / inaposhindwa.