ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Webhooks

telephony.complete / web.complete

Neblokirajoč webhook, poslan ob koncu klica, s prepisom, URL-jem posnetka in metrikami.

Dogodek dokončanja se sproži po koncu vsakega klica — dohodne telefonije, odhodne telefonije, spletnega klica ali preskusnega klica (seja z mikrofonom v gradniku). Je neblokirajoč: odgovorite s katerim koli 2xx.

Dogodek je dostavljen po obeh poteh:

Telo zahteve (dostave končne točke)

{
  "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"
}
PoljeVrstaOpis
call_idintegerNespremenljiv v vseh dogodkih za ta klic
agent_idinteger | nullGlasovni agent, ki je obravnaval klic, kadar je bil dodeljen
agent_namestring | nullGlasovni agent, ki je obravnaval klic, kadar je bil dodeljen
directionstringinbound, outbound, web, test. Zgodovinski koristni podatki lahko vsebujejo podedovani vrednosti mic ali widget
from_number, to_numberstringE.164. from_number je dobesedna vrednost "web" za spletne klice in preskusne klice
origin_domainstringSamo za spletne/preskusne klice — izvor strani, ki je gostila gradnik (prazno za seje mikrofona)
start_time, end_timetimestampISO 8601 UTC
duration_secondsinteger | nullIzpeljano iz časa začetka/konca
statusstringcompleted ali failed
end_reasonstringGlejte spodnjo tabelo
answered_bystring | nullSamo odhodni telefonski klici (sicer ni prisotno): kdo je odgovoril, human, voicemail, screener (pomočnik za pregledovanje klicev), ivr (telefonski meni) ali unknown. null, kadar ni odgovoril nihče, in vedno null v dogodkih migration.call.complete za odhodne klice, ki jih je obravnavala platforma, s katere se selite. Enake vrednosti kot pri objektu klica
product, voicestringKonfiguracija agenta, veljavna ob času klica
variablesobjectVhodne spremenljivke, zajete ob začetku klica
unresolved_variablesarrayImena spremenljivk, na katere se sklicuje konfiguracija klica, vendar ob začetku klica niso bile podane
transfer_numberstring | nullNastavljeno, ko je bil klic preusmerjen
scheduled_send_idstringSamo pri klicu, opravljenem z načrtovanim pošiljanjem: ID tega pošiljanja. Pri vseh drugih klicih ni prisotno
recording_urlstring | nullČasovno omejen podpisan URL; prenesite ga takoj. null, kadar posnetek ni na voljo
recording_stopped_attimestamp | nullKdaj je bilo snemanje ustavljeno pred koncem klica; po tem trenutku na posnetku ni ničesar. null, kadar je snemanje trajalo do konca klica ali klic ni bil posnet
recording_stopped_reasonstring | nullZakaj se je snemanje predčasno ustavilo. warm_transfer: ustavi se tik preden topla preusmeritev pokliče cilj, in ostane izklopljeno tudi, če preusmeritev ne uspe in se klicatelj vrne k agentu. Druge vrednosti obravnavajte kot informativne; lahko bodo dodane nove. null, kadar je recording_stopped_at null
billable_minutesnumberZaračunane minute, zaokrožene na najbližjo četrt minute (15-sekundni koraki, najmanj 0.25). Klici neposredno v glasovno pošto tukaj še vedno navajajo dejansko merjene minute, vendar je strošek omejen na eno minuto po ceni paketa.
billing_total_centsinteger | nullCenti USD. null, dokler je billing_pending true
billing_pendingbooleanPrisotno samo kot true pri merjenem klicu, katerega strošek še ni poravnan: merjeni klic se zaračuna nekaj minut po koncu, ko je njegova poraba zabeležena, zato sta billable_minutes in billing_total_cents tukaj null, strošek pa prispe v call.billed. Pri vseh drugih klicih ni prisotno
transcriptsarrayVnosi prepisa po posameznih potezah; lahko je prazno, kadar prepis ni na voljo
summarystring | nullPovzetek po klicu v običajnem jeziku (dva do štirje stavki proze, največ 2.000 znakov, napisan v agentovem jeziku summary_language, sicer v jeziku povzetkov organizacije, sicer v jeziku klica: primarnem jeziku agenta, razen če ga je klic preglasil), kadar ima agent v gradniku agenta v razdelku Podatki za zbiranje vklopljeno možnost Ustvari povzetek klica (call_summary_enabled pri Agentu) in je ustvarjanje uspelo; sicer null, vključno pri klicih, prekratkih za povzemanje, klicih brez prepisa in agentih z izklopljenim snemanjem. Povzetek se ustvari v istem koraku po klicu kot ekstrakcija, zato nastavitev Počakajte na ekstrahirane podatke pred pošiljanjem webhooka ob koncu klica (extraction_blocks_completion) določa, ali ta dogodek čaka nanj: v načinu čakanja je povzetek pripravljen pred pošiljanjem tega dogodka (sam povzetek ima znotraj 75-sekundnega proračuna koraka na voljo največ 30 sekund); kadar dogodek ne čaka (never ali preusmeritev oziroma vrnitev v vaš kontaktni center v okviru except_transfers), je to polje null in povzetek se ne pošlje znova v call.data_extracted, zato ga pozneje preberite iz summary v objektu klica. Na voljo je tudi na strani klica na nadzorni plošči
extracted_dataobject | nullStrukturiran rezultat ekstrakcije s status, fields, evidence, verification, field_reasons in schema_version. Vsako polje, ki ni null, vsebuje natančen strukturno preverjen citat (največ 1.000 znakov) ter vlogo govorca in indeks poteze; daljši citati, ki jih vrne model, so zavrnjeni namesto okrajšani. Dokaz je null, kadar je polje null. verified pomeni, da je vsak kandidat prejel natanko eno veljavno neodvisno presojo. unavailable zajema tudi nepravilno oblikovan ali delen izhod preverjevalnika; veljavne delne presoje še vedno veljajo, kandidati brez ene veljavne presoje pa so nastavljeni na null. status je completed, failed, exhausted, skipped ali skipped_recording_disabled; null, kadar agent ni imel polj za ekstrakcijo
steps_tracearraySamo pri klicih, katerih agent ima korake ali predaje. Vrstni red, po katerem je klic potoval skozi njih: vsak vnos ima t_ms (milisekunde od začetka klica), agent (ključ agenta, a in njegov ID), step (ID koraka ali null pri predaji agentu brez korakov) in via (start, model, condition, on_enter ali handoff). Vsebuje samo ID-je in čase, zato se ohrani tudi, kadar je snemanje izklopljeno
collected_valuesobjectSamo pri klicih, katerih agent ima korake ali predaje. Vrednosti, ki jih je agent zbral v svojih korakih, razvrščene po imenu polja zbiranja, ter <tool>_result za rezultat on_enter_tool vsakega koraka. Izpuščeno, kadar vsebina klica ni shranjena (snemanje je izklopljeno)

Razlogi za konec

VrednostPomen
user_hangupOddaljena stranka je prva prekinila klic
ai_hangupUI je klic namerno končala
ai_transferUI je klic preusmerila; transfer_number je nastavljen
ai_warm_transferUI je dokončala toplo (sprejeto) preusmeritev
returned_to_platformUI je vrnila klic v vaš kontaktni center: prekinila je klic, pri čemer so bile glave vnosa za vrnitev v SIP BYE, če obstajajo
voicemail_hangupZaznan je bil glasovni predal, klic pa se je končal v skladu z vašim voicemail_action
max_durationKlic je dosegel omejitev najdaljšega trajanja: omejitev agenta, lastno omejitev klica ali 6-urno omejitev platforme. Klic, ki ga UI ali klicatelj konča po opozorilu o časovni omejitvi, ohrani ai_hangup ali user_hangup
supersededSejo je zamenjala novejša seja
inbound_config_webhook_failedDohodni klic na številko v načinu webhook: konfiguracijski webhook ni vrnil uporabne konfiguracije, zato se je klic končal, preden je agent odgovoril. status je failed in klic se ne zaračuna
outbound_queue_timeoutKlic v čakalni vrsti je čakal 10 minut brez možnosti za klicanje. status je failed, nič ni bilo poklicano in klic se ne zaračuna
outbound_queue_canceledPreklicali ste klic v čakalni vrsti, preden se je začelo klicanje. status je failed in klic se ne zaračuna
unknownRazloga za konec ni bilo mogoče določiti

Oblika prepisa

Vsak vnos v transcripts predstavlja en pogovorni obrat. Vloge so user (govor klicatelja), model (govor agenta in klici orodij), tool (rezultati orodij) in system (dogodki klica, kot so preklopi jezika).

[
  {
    "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"] }
    }
  }
]
PoljeVrstaOpis
rolenizuser, model, tool ali system
content_typeniztext/plain za govor; application/json za klice orodij, rezultate orodij in sistemske dogodke
contentniz | objektBesedilo govora ali strukturirani objekt, prikazan zgoraj. Klici orodij: {"tool_call": name, "arguments": {…}}. Rezultati orodij: {"tool_name": name, "response": {…}}
start_ms, end_mscelo številoOdmika od začetka klica v ms. Prisotna, kadar je časovni potek zvoka znan
ttfa_mscelo številoČas do prvega zvoka za obrat model, kadar je izmerjen
audio_url, audio_urlsniz / poljeURL-ji s podpisom in omejenim rokom veljavnosti za zvok obrata, kadar se zvok snema za posamezni obrat

Za celotno strukturirano zgodovino obratov (z oznakami prekinitev, pozivi za potrditev in neobdelanimi položaji) uporabite GET /v1/calls/{call_id}/history.

Razlike v starejšem podatkovnem paketu

Starejša ovojnica webhooka z enim URL-jem je {"type": "telephony.complete" | "web.complete", "data": {…}} brez event_id, njen data pa se razlikuje od podatkovnega paketa končne točke:

Starejši podatkovni paket ob zaključku vsebuje tudi agent_id in agent_name.

  • Polje obratov je pod history, ne pod transcripts (z enako shemo obratov kot zgoraj).
  • Nabor polj je neobdelano poročilo ob koncu klica in lahko vključuje dodatna interna polja poleg zgornje tabele — neznana polja obravnavajte kot informativna.
  • Spletni klici (direction: "web") ne vključujejo from_number / to_number in dodajo origin_domain.
  • Klici za preizkus mikrofona v orodju Builder se na starejši poti poročajo kot telephony.complete (sistem končne točke jih preslika v web.complete).
  • Usklajevanje prenosa: kadar se klic konča s prenosom, se starejši webhook pokliče sinhrono in lahko vrne {"transfer_ready": false}, kar sporoča, da cilj prenosa še ni pripravljen. Vsak drug odgovor (ali odsotnost starejšega webhooka) omogoči nadaljevanje prenosa. Dostave končne točke se za to nikoli ne preverjajo.

Primer obdelovalnika

Python (FastAPI)
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}
Node.js (Express)
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 });
  },
);

Pogosti primeri uporabe

Integracija s CRM-jem

Shranite prepis in URL posnetka vsakega klica skupaj z zapisi o strankah.

Analitika

Pretakajte prepise v cevovod za modeliranje tem, pridobivanje signalov CSAT ali spremljanje stopnje preusmeritev.

Pregled kakovosti

Odprite klice v orodju QA za človeški pregled ali jih obdelajte z lastnim modelom za ocenjevanje.

Obvestila

Ob preusmeritvi / napaki obvestite člana ekipe.


Povezano