ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Webhooks

telephony.complete / web.complete

Neblokirajući webhook isporučen po završetku poziva, s transkriptom, URL-om snimke i metrikama.

Događaj dovršetka pokreće se nakon završetka svakog poziva — dolazne telefonije, odlazne telefonije, web-poziva ili probnog poziva (sesija mikrofona u alatu za izradu). On je neblokirajući: odgovorite bilo kojim statusom 2xx.

Događaj se isporučuje na oba puta:

Tijelo zahtjeva (isporuke krajnjoj točki)

{
  "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_idintegerStabilan u svim događajima za ovaj poziv
agent_idinteger | nullAgent koji je obradio poziv, ako je dodijeljen
agent_namestring | nullAgent koji je obradio poziv, ako je dodijeljen
directionstringinbound, outbound, web, test. Povijesni payloadi mogu sadržavati zastarjele vrijednosti mic ili widget
from_number, to_numberstringE.164. from_number doslovno je "web" za web-pozive i testne pozive
origin_domainstringSamo za web/test — ishodište stranice na kojoj je hostan widget (prazno za mic sesije)
start_time, end_timetimestampISO 8601 UTC
duration_secondsinteger | nullIzvedeno iz početka/završetka
statusstringcompleted ili failed
end_reasonstringPogledajte tablicu u nastavku
answered_bystring | nullSamo odlazni telefonski pozivi (inače nije prisutno): tko se javio, human, voicemail, screener (pomoćnik za provjeru poziva), ivr (telefonski izbornik) ili unknown. null kada se nitko nije javio te uvijek null u događajima migration.call.complete za odlazne pozive koje je obradila platforma s koje prelazite. Iste vrijednosti kao u objektu poziva
product, voicestringKonfiguracija agenta aktivna u trenutku poziva
variablesobjectUlazne varijable snimljene pri početku poziva
unresolved_variablesarrayNazivi varijabli na koje se poziva konfiguracija poziva, ali nisu dostavljene pri početku poziva
transfer_numberstring | nullPostavljeno kada je poziv preusmjeren
scheduled_send_idstringSamo za poziv upućen zakazanim slanjem: ID tog slanja. Nije prisutno ni u jednom drugom pozivu
recording_urlstring | nullPotpisani URL s istekom; odmah preuzmite. null kada snimka nije dostupna
recording_stopped_attimestamp | nullVrijeme kada je snimanje zaustavljeno prije završetka poziva; ništa nakon tog trenutka nije u snimci. null kada je snimanje trajalo do kraja poziva ili poziv nije snimljen
recording_stopped_reasonstring | nullZašto je snimanje rano zaustavljeno. warm_transfer: zaustavlja se neposredno prije nego što toplo preusmjeravanje nazove odredište i ostaje isključeno čak i ako preusmjeravanje ne uspije te se pozivatelj vrati agentu. Ostale vrijednosti smatrajte informativnima; mogu se dodati nove. null kada je recording_stopped_at null
billable_minutesnumberNaplaćene minute, zaokružene na najbližu četvrtinu minute (intervali od 15 sekundi, najmanje 0.25). Pozivi izravno na govornu poštu ovdje i dalje prikazuju svoje stvarne izmjerene minute, ali je naknada ograničena na jednu minutu po cijeni plana.
billing_total_centsinteger | nullAmerički centi. null dok je billing_pending true
billing_pendingbooleanPrisutan samo kao true za poziv s mjerenom naplatom čija naknada još nije obrađena: poziv s mjerenom naplatom naplaćuje se nekoliko minuta nakon završetka, kada se zaprimi njegova potrošnja, pa su billable_minutes i billing_total_cents ovdje null, a naknada stiže u call.billed. Nije prisutan ni u jednom drugom pozivu
transcriptsarrayUnosi transkripta po potezu; može biti prazno kada transkript nije dostupan
summarystring | nullSažetak nakon poziva na običnom jeziku (dvije do četiri rečenice proznog teksta, najviše 2.000 znakova, napisan na agentovu jeziku summary_language, inače na jeziku sažetaka organizacije, inače na jeziku poziva: primarnom jeziku agenta, osim ako ga poziv nije nadjačao) kada agent ima uključenu opciju Generiraj sažetak poziva u odjeljku Podaci za prikupljanje u alatu za izradu agenta (call_summary_enabled na Agentu) i generiranje je uspjelo; inače null, uključujući pozive prekratke za sažimanje, pozive bez transkripta i agente s isključenim snimanjem. Sažetak se generira u istom koraku nakon poziva kao i ekstrakcija, pa postavka Pričekajte izdvojene podatke prije slanja webhooka o završenom pozivu (extraction_blocks_completion) određuje čeka li ovaj događaj na njega: u načinu čekanja sažetak je spreman prije slanja ovog događaja (sam sažetak ima najviše 30 sekundi unutar proračuna koraka od 75 sekundi); kada događaj ne čeka (never, ili preusmjeravanje ili povratak u vaš kontaktni centar uz except_transfers), ovo je polje null i sažetak se ne šalje ponovno u call.data_extracted, stoga ga kasnije pročitajte iz summary u objektu poziva. Dostupno je i na stranici poziva na nadzornoj ploči
extracted_dataobject | nullStrukturirani rezultat ekstrakcije s poljima status, fields, evidence, verification, field_reasons i schema_version. Svako polje koje nije null ima točan strukturno provjeren citat (najviše 1.000 znakova), uz ulogu govornika i indeks poteza; dulji citati koje vrati model odbacuju se umjesto skraćivanja. Dokaz je null kada je polje null. verified znači da je svaki kandidat primio točno jednu valjanu neovisnu presudu. unavailable obuhvaća i neispravan ili djelomičan izlaz provjeravatelja; valjane djelomične presude i dalje se primjenjuju, dok se kandidati bez jedne valjane presude postavljaju na null. status je completed, failed, exhausted, skipped ili skipped_recording_disabled; null kada agent nije imao polja za ekstrakciju
steps_tracearraySamo za pozive čiji agent ima korake ili predaje. Redoslijed kojim je poziv prolazio kroz njih: svaki unos ima t_ms (milisekunde od početka poziva), agent (ključ agenta, a plus njegov ID), step (ID koraka ili null pri predaji agentu bez koraka) i via (start, model, condition, on_enter ili handoff). Sadrži samo ID-ove i vremena, stoga se čuva i kada je snimanje isključeno
collected_valuesobjectSamo za pozive čiji agent ima korake ili predaje. Vrijednosti koje je agent prikupio u svojim koracima, označene nazivom polja za prikupljanje, uz <tool>_result za rezultat on_enter_tool svakog koraka. Izostavljeno kada se sadržaj poziva ne zadržava (snimanje je isključeno)

Razlozi završetka

VrijednostZnačenje
user_hangupUdaljena strana prva je prekinula vezu
ai_hangupAI je namjerno završio poziv
ai_transferAI je preusmjerio poziv; transfer_number je postavljen
ai_warm_transferAI je dovršio topli (najavljeni) prijenos
returned_to_platformAI je vratio poziv u vaš kontaktni centar: prekinuo je vezu, s zaglavljima povratnog unosa u SIP poruci BYE ako postoje
voicemail_hangupOtkrivena je govorna pošta i poziv je završen prema vašem voicemail_action
max_durationPoziv je dosegnuo ograničenje maksimalnog trajanja: ograničenje agenta, vlastito ograničenje poziva ili ograničenje platforme od 6 sati. Poziv koji AI ili pozivatelj završi nakon upozorenja o vremenskom ograničenju zadržava ai_hangup ili user_hangup
supersededSesiju je zamijenila novija sesija
inbound_config_webhook_failedDolazni poziv na broj u načinu rada webhooka: webhook za konfiguraciju nije vratio upotrebljivu konfiguraciju, pa je poziv završen prije nego što se agent javio. status je failed i poziv se ne naplaćuje
outbound_queue_timeoutPoziv u redu čekanja čekao je 10 minuta bez dostupnog kapaciteta za biranje. status je failed, ništa nije birano i poziv se ne naplaćuje
outbound_queue_canceledOtkazali ste poziv u redu čekanja prije nego što je biran. status je failed i poziv se ne naplaćuje
unknownRazlog završetka nije se mogao utvrditi

Format prijepisa

Svaki unos u transcripts predstavlja jedan razgovorni potez. Uloge su user (govor pozivatelja), model (govor agenta i pozivi alata), tool (rezultati alata) i system (događaji poziva kao što su promjene 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
rolestringuser, model, tool ili system
content_typestringtext/plain za govor; application/json za pozive alata, rezultate alata i sistemske događaje
contentstring | objectTekst govora ili strukturirani objekt prikazan iznad. Pozivi alata: {"tool_call": name, "arguments": {…}}. Rezultati alata: {"tool_name": name, "response": {…}}
start_ms, end_msintegerPomaci od početka poziva, u ms. Prisutni kada je poznato vremensko usklađivanje zvuka
ttfa_msintegerVrijeme do prvog zvuka za potez model, kada je izmjereno
audio_url, audio_urlsstring / arrayIstječući potpisani URL-ovi za zvuk poteza, kada se zvuk snima po potezu

Za potpuno strukturiranu povijest poteza (s oznakama prekida, upitima za potvrdu i sirovim pozicijama) upotrijebite GET /v1/calls/{call_id}/history.

Razlike u naslijeđenom payloadu

Naslijeđena omotnica webhooka s jednim URL-om je {"type": "telephony.complete" | "web.complete", "data": {…}} bez event_id, a njezin se data razlikuje od payloada krajnje točke:

Naslijeđeni payload dovršetka također sadrži agent_id i agent_name.

  • Niz poteza nalazi se pod history, a ne pod transcripts (ista shema poteza kao iznad).
  • Skup polja predstavlja sirovi izvještaj na kraju poziva i može sadržavati dodatna interna polja izvan gornje tablice — nepoznata polja tretirajte kao informativna.
  • Web-pozivi (direction: "web") izostavljaju from_number / to_number i dodaju origin_domain.
  • Pozivi za testiranje mikrofona u Builderu prijavljuju se kao telephony.complete na naslijeđenoj putanji (sustav krajnje točke mapira ih na web.complete).
  • Koordinacija prijenosa: kada poziv završi prijenosom, naslijeđeni webhook poziva se sinkrono i može odgovoriti s {"transfer_ready": false} kako bi signalizirao da cilj prijenosa nije spreman. Svaki drugi odgovor (ili izostanak naslijeđenog webhooka) omogućuje nastavak prijenosa. Isporuke krajnjoj točki nikada se ne provjeravaju u tu svrhu.

Primjer rukovatelja

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 });
  },
);

Uobičajeni slučajevi upotrebe

Integracija s CRM-om

Pohranite transkript i URL snimke svakog poziva uz evidenciju svojih korisnika.

Analitika

Šaljite transkripte u proces obrade za modeliranje tema, izdvajanje CSAT signala ili praćenje stope prijenosa.

Pregled kvalitete

Otvorite pozive u alatu za osiguranje kvalitete radi pregleda od strane ljudi ili ih obradite vlastitim modelom za evaluaciju.

Obavijesti

Obavijestite člana tima pri prijenosu / neuspjehu.


Povezano