ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Webhooks

telephony.complete / web.complete

Neblokujúci webhook doručený po ukončení hovoru s prepisom, URL nahrávky a metrikami.

Udalosť dokončenia sa spustí po skončení každého hovoru — prichádzajúcej telefónie, odchádzajúcej telefónie, webového hovoru alebo testovacieho hovoru (relácia mikrofónu v nástroji na tvorbu). Je neblokujúca: odpovedzte ľubovoľným kódom 2xx.

Udalosť sa doručuje oboma cestami:

Telo požiadavky (doručenia endpointu)

{
  "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"
}
PoleTypPopis
call_idcelé čísloStabilné vo všetkých udalostiach pre tento hovor
agent_idcelé číslo | nullAgent, ktorý spracoval hovor, ak bol priradený
agent_namereťazec | nullAgent, ktorý spracoval hovor, ak bol priradený
directionreťazecinbound, outbound, web, test. Historické payloady môžu obsahovať staršie hodnoty mic alebo widget
from_number, to_numberreťazecE.164. from_number je doslovná hodnota "web" pre webové a testovacie hovory
origin_domainreťazecLen pre web/test — pôvod stránky, na ktorej bol hostovaný widget (prázdne pre relácie mic)
start_time, end_timečasová značkaISO 8601 UTC
duration_secondscelé číslo | nullOdvodené od času začiatku a konca
statusreťazeccompleted alebo failed
end_reasonreťazecPozrite si tabuľku nižšie
answered_byreťazec | nullLen pre odchádzajúce telefonické hovory (inak chýba): kto odpovedal, human, voicemail, screener (asistent na filtrovanie hovorov), ivr (telefónne menu) alebo unknown. null, keď nikto neodpovedal, a vždy null v udalostiach migration.call.complete pre odchádzajúce hovory, ktoré spracovala platforma, z ktorej prechádzate. Rovnaké hodnoty ako v objekte hovoru
product, voicereťazecKonfigurácia agenta platná v čase hovoru
variablesobjektVstupné premenné zachytené pri začatí hovoru
unresolved_variablespoleNázvy premenných, na ktoré odkazuje konfigurácia hovoru, ale neboli poskytnuté pri začatí hovoru
transfer_numberreťazec | nullNastavené pri presmerovaní hovoru
scheduled_send_idreťazecLen pri hovore uskutočnenom prostredníctvom naplánovaného odoslania: ID daného odoslania. Pri všetkých ostatných hovoroch chýba
recording_urlreťazec | nullPodpísaná adresa URL s obmedzenou platnosťou; stiahnite ju bezodkladne. null, keď nie je k dispozícii žiadny záznam
recording_stopped_atčasová značka | nullKeď sa nahrávanie zastavilo pred ukončením hovoru; nič po tomto okamihu sa v nahrávke nenachádza. null, keď nahrávanie pokračovalo až do konca hovoru alebo hovor nebol nahrávaný
recording_stopped_reasonreťazec | nullPrečo sa nahrávanie zastavilo predčasne. warm_transfer: zastaví sa tesne predtým, ako teplé presmerovanie zavolá cieľovému kontaktu, a zostane vypnuté aj v prípade zlyhania presmerovania a návratu volajúceho k agentovi. Ostatné hodnoty považujte za informatívne; môžu pribudnúť ďalšie. null, keď recording_stopped_at je null
billable_minutesčísloFakturované minúty zaokrúhlené na najbližšiu štvrťminútu (15-sekundové intervaly, minimum 0.25). Hovory priamo do hlasovej schránky tu stále uvádzajú skutočné merané minúty, ale poplatok je obmedzený na jednu minútu podľa sadzby plánu.
billing_total_centscelé číslo | nullCenty USD. null, kým billing_pending je true
billing_pendingbooleanPrítomné iba ako true pri meranom hovore, ktorého poplatok ešte nebol vyúčtovaný: meraný hovor sa účtuje niekoľko minút po skončení, po prijatí údajov o jeho využití, takže billable_minutes a billing_total_cents sú tu null a poplatok príde v call.billed. Pri všetkých ostatných hovoroch chýba
transcriptspoleZáznamy prepisu jednotlivých ťahov; môžu byť prázdne, keď prepis nie je k dispozícii
summaryreťazec | nullSúhrn po hovore v prirodzenom jazyku (dve až štyri vety prózy, najviac 2 000 znakov, napísaný v summary_language agenta, inak v jazyku súhrnov organizácie, inak v jazyku hovoru: primárnom jazyku agenta, ak ho hovor neprepísal), keď má agent v nástroji na vytváranie agentov v časti Údaje na zhromaždenie zapnutú možnosť Generovať súhrn hovoru (call_summary_enabled v Agentovi) a generovanie bolo úspešné; inak null, vrátane hovorov príliš krátkych na zhrnutie, hovorov bez prepisu a agentov s vypnutým nahrávaním. Súhrn sa generuje v rovnakom kroku po hovore ako extrakcia, takže nastavenie Počkať na extrahované údaje pred odoslaním webhooku o ukončení hovoru (extraction_blocks_completion) určuje, či naň táto udalosť čaká: v režime čakania je súhrn pripravený pred odoslaním tejto udalosti (samotný súhrn má v rámci 75-sekundového rozpočtu kroku najviac 30 sekúnd); keď udalosť nečaká (never, alebo presmerovanie či návrat do vášho kontaktného centra pri except_transfers), toto pole je null a súhrn sa neodosiela znova v call.data_extracted, preto ho neskôr načítajte z summary v objekte hovoru. K dispozícii je aj na stránke hovoru v ovládacom paneli
extracted_dataobjekt | nullVýsledok štruktúrovanej extrakcie s položkami status, fields, evidence, verification, field_reasons a schema_version. Každé pole, ktoré nie je null, obsahuje presnú štrukturálne overenú citáciu (najviac 1 000 znakov), ako aj rolu hovoriaceho a index ťahu; dlhšie citácie vrátené modelom sa namiesto skrátenia odmietnu. Dôkaz je null, keď je pole null. verified znamená, že každý kandidát dostal presne jeden platný nezávislý verdikt. unavailable zahŕňa aj nesprávne formátovaný alebo neúplný výstup overovača; platné čiastočné verdikty sa naďalej použijú, zatiaľ čo kandidáti bez jedného platného verdiktu sa nastavia na null. status je completed, failed, exhausted, skipped alebo skipped_recording_disabled; null, keď agent nemal žiadne extrakčné polia
steps_tracepoleLen pri hovoroch, ktorých agent má kroky alebo odovzdania. Poradie, v akom hovor nimi prechádzal: každá položka obsahuje t_ms (milisekundy od začatia hovoru), agent (kľúč agenta, a plus jeho ID), step (ID kroku alebo null pri odovzdaní agentovi bez krokov) a via (start, model, condition, on_enter alebo handoff). Obsahuje len ID a časy, takže sa uchováva aj pri vypnutom nahrávaní
collected_valuesobjektLen pri hovoroch, ktorých agent má kroky alebo odovzdania. Hodnoty, ktoré agent zhromaždil vo svojich krokoch, s kľúčom podľa názvu poľa zhromažďovania, plus <tool>_result pre výsledok on_enter_tool každého kroku. Vynechá sa, keď sa obsah hovoru neuchováva (nahrávanie je vypnuté)

Dôvody ukončenia

HodnotaVýznam
user_hangupVzdialená strana zavesila ako prvá
ai_hangupAI zámerne ukončila hovor
ai_transferAI presmerovala hovor; transfer_number je nastavené
ai_warm_transferAI dokončila teplé (asistované) presmerovanie
returned_to_platformAI vrátila hovor do vášho kontaktného centra: zavesila a pri existujúcich hlavičkách záznamu o vrátení ich zahrnula do SIP BYE
voicemail_hangupBola zistená hlasová schránka a hovor sa ukončil podľa vášho voicemail_action
max_durationHovor dosiahol limit maximálneho trvania: limit agenta, vlastný limit hovoru alebo 6-hodinový limit platformy. Hovor, ktorý AI alebo volajúci ukončí po upozornení na časový limit, si zachová ai_hangup alebo user_hangup
supersededRelácia bola nahradená novšou
inbound_config_webhook_failedPrichádzajúci hovor na číslo v režime webhooku: konfiguračný webhook nevrátil použiteľnú konfiguráciu, preto bol hovor ukončený pred odpoveďou agenta. status je failed a hovor nie je spoplatnený
outbound_queue_timeoutHovor vo fronte čakal 10 minút bez dostupnej kapacity na vytočenie. status je failed, nič sa nevytočilo a hovor nie je spoplatnený
outbound_queue_canceledZrušili ste hovor vo fronte pred jeho vytočením. status je failed a hovor nie je spoplatnený
unknownDôvod ukončenia sa nepodarilo určiť

Formát prepisu

Každá položka v transcripts predstavuje jeden konverzačný ťah. Roly sú user (reč volajúceho), model (reč agenta a volania nástrojov), tool (výsledky nástrojov) a system (udalosti hovoru, napríklad zmeny jazyka).

[
  {
    "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"] }
    }
  }
]
PoleTypPopis
rolestringuser, model, tool alebo system
content_typestringtext/plain pre reč; application/json pre volania nástrojov, výsledky nástrojov a systémové udalosti
contentstring | objectText reči alebo štruktúrovaný objekt zobrazený vyššie. Volania nástrojov: {"tool_call": name, "arguments": {…}}. Výsledky nástrojov: {"tool_name": name, "response": {…}}
start_ms, end_msintegerPosuny od začiatku hovoru v ms. Uvádzajú sa, keď je známe časovanie zvuku
ttfa_msintegerČas do prvého zvuku pre ťah model, ak sa meria
audio_url, audio_urlsstring / arrayURL s časovo obmedzeným podpisom pre zvuk daného ťahu, ak sa zaznamenáva pre jednotlivé ťahy

Pre úplne štruktúrovanú históriu ťahov (so značkami prerušení, výzvami na potvrdenie a nespracovanými pozíciami) použite GET /v1/calls/{call_id}/history.

Rozdiely staršieho payloadu

Starší obal webhooku s jednou URL je {"type": "telephony.complete" | "web.complete", "data": {…}} bez event_id a jeho data sa líši od payloadu endpointu:

Starší payload dokončenia obsahuje aj agent_id a agent_name.

  • Pole ťahov je v history, nie v transcripts (s rovnakou schémou ťahov ako vyššie).
  • Sada polí predstavuje nespracovaný report po ukončení hovoru a môže obsahovať ďalšie interné polia nad rámec tabuľky vyššie — neznáme polia považujte za informatívne.
  • Webové hovory (direction: "web") neobsahujú from_number / to_number a pridávajú origin_domain.
  • Testovacie hovory mikrofónu v nástroji Builder sa na staršej ceste hlásia ako telephony.complete (systém endpointu ich mapuje na web.complete).
  • Koordinácia presmerovania: keď sa hovor skončí presmerovaním, starší webhook sa volá synchrónne a môže odpovedať {"transfer_ready": false}, čím signalizuje, že cieľ presmerovania nie je pripravený. Akákoľvek iná odpoveď (alebo žiadny starší webhook) umožní pokračovanie presmerovania. Doručenia endpointu sa na tento účel nikdy nekontrolujú.

Ukážkový obslužný program

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

Bežné prípady použitia

Integrácia CRM

Uložte prepis každého hovoru a adresu URL nahrávky spolu so záznamami o zákazníkoch.

Analytika

Streamujte prepisy do pipeline na modelovanie tém, extrakciu signálov CSAT alebo monitorovanie miery presmerovaní.

Kontrola kvality

Otvorte hovory v nástroji QA na kontrolu človekom alebo ich spustite cez vlastný hodnotiaci model.

Oznámenia

Pri presmerovaní alebo zlyhaní upozornite člena tímu.


Súvisiace