ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Webhooks

telephony.complete / web.complete

Neblokuojantis žiniatinklio kabliukas, pateikiamas pasibaigus skambučiui, su transkriptu, įrašo URL ir metrika.

Užbaigimo įvykis suaktyvinamas pasibaigus kiekvienam skambučiui – įeinančios telefonijos, išeinančios telefonijos, žiniatinklio skambučiui arba bandomajam skambučiui (kūrimo priemonės mikrofono seansui). Jis yra neblokuojantis: atsakykite bet kokiu 2xx kodu.

Įvykis pristatomas abiem keliais:

Užklausos paketas (galinių taškų pristatymai)

{
  "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"
}
LaukasTipasAprašas
call_idsveikasis skaičiusPastovus visuose šio skambučio įvykiuose
agent_idsveikasis skaičius | nullSkambutį aptarnavęs agentas, jei jis buvo priskirtas
agent_nameeilutė | nullSkambutį aptarnavusio agento vardas, jei jis buvo priskirtas
directioneilutėinbound, outbound, web, test. Istoriniuose duomenų paketuose gali būti senesnės mic arba widget reikšmės
from_number, to_numbereilutėE.164. Žiniatinklio ir bandomiesiems skambučiams from_number yra pažodinė reikšmė "web"
origin_domaineilutėTik žiniatinklio ir bandomiesiems skambučiams — puslapio, kuriame buvo įterptas valdiklis, kilmė (mikrofono seansams tuščia)
start_time, end_timelaiko žymaISO 8601 UTC
duration_secondssveikasis skaičius | nullApskaičiuojama pagal pradžios ir pabaigos laiką
statuseilutėcompleted arba failed
end_reasoneilutėŽr. toliau pateiktą lentelę
answered_byeilutė | nullTik išeinantiems telefono skambučiams (kitais atvejais nėra): kas atsiliepė — human, voicemail, screener (skambučių tikrinimo asistentas), ivr (telefono meniu) arba unknown. null, kai niekas neatsiliepė, ir visada null migration.call.complete įvykiuose, skirtuose išeinantiems skambučiams, kuriuos aptarnavo platforma, iš kurios pereinate. Tos pačios reikšmės kaip skambučio objekte
product, voiceeilutėSkambučio metu galiojusi agento konfigūracija
variablesobjektasĮvesties kintamųjų momentinė kopija skambučio pradžioje
unresolved_variablesmasyvasKintamųjų pavadinimai, nurodyti skambučio konfigūracijoje, bet nepateikti skambučio pradžioje
transfer_numbereilutė | nullNustatoma, kai skambutis buvo peradresuotas
scheduled_send_ideilutėTik skambučiui, atliktam naudojant suplanuotą siuntimą: to siuntimo ID. Visuose kituose skambučiuose nėra
recording_urleilutė | nullLaikinai galiojantis pasirašytas URL; atsisiųskite nedelsdami. null, kai nėra įrašo artefakto
recording_stopped_atlaiko žyma | nullKai įrašymas buvo sustabdytas prieš skambučio pabaigą; po šio momento įraše nieko nėra. null, kai įrašymas tęsėsi iki skambučio pabaigos arba skambutis nebuvo įrašytas
recording_stopped_reasoneilutė | nullKodėl įrašymas buvo sustabdytas anksčiau. warm_transfer: jis sustabdomas prieš pat šiltajam peradresavimui skambinant į paskirties vietą ir lieka išjungtas, net jei peradresavimas nepavyksta ir skambinantysis grįžta pas agentą. Kitas reikšmes laikykite informacinėmis; jų gali būti pridėta daugiau. null, kai recording_stopped_at yra null
billable_minutesskaičiusApmokestintos minutės, suapvalintos iki artimiausio ketvirčio minutės (15 sekundžių intervalais, mažiausiai 0.25). Skambučiai tiesiai į balso paštą čia vis tiek nurodo faktines apskaitytas minutes, tačiau mokestis ribojamas iki vienos minutės pagal plano tarifą.
billing_total_centssveikasis skaičius | nullUSD centai. null, kol billing_pending yra true
billing_pendingloginė reikšmėRodoma tik kaip true apskaičiuojamam skambučiui, kurio mokestis dar nenustatytas: apskaičiuojamas skambutis apmokestinamas praėjus kelioms minutėms po jo pabaigos, kai gaunami naudojimo duomenys, todėl billable_minutes ir billing_total_cents čia yra null, o mokestis pateikiamas call.billed. Visuose kituose skambučiuose nėra
transcriptsmasyvasPokalbio transkripto įrašai kiekvienam ėjimui; gali būti tuščias, kai transkriptas nepasiekiamas
summaryeilutė | nullPaprasta kalba parašyta santrauka po skambučio (nuo dviejų iki keturių prozos sakinių, daugiausia 2 000 simbolių, parašyta agento summary_language, kitu atveju organizacijos santraukų kalba, o kitu atveju skambučio kalba: pagrindine agento kalba, nebent skambutis ją pakeitė), kai agentui agento kūrimo priemonėje skiltyje Renkami duomenys įjungta Generuoti skambučio santrauką (call_summary_enabled Agente) ir generavimas pavyko; kitu atveju null, įskaitant skambučius, kurie per trumpi apibendrinti, skambučius be transkripto ir agentus, kuriems įrašymas išjungtas. Santrauka generuojama tame pačiame etape po skambučio kaip ir ištraukimas, todėl nustatymas Laukti ištrauktų duomenų prieš siunčiant skambučio pabaigos žiniatinklio kablį (extraction_blocks_completion) lemia, ar šis įvykis jos laukia: laukimo režimu santrauka paruošiama prieš siunčiant šį įvykį (pačiai santraukai etapo 75 sekundžių biudžete skiriama ne daugiau kaip 30 sekundžių); kai įvykis nelaukia (never, peradresavus arba grįžus į jūsų kontaktų centrą pagal except_transfers), šis laukas yra null, o santrauka nėra iš naujo siunčiama per call.data_extracted, todėl vėliau perskaitykite ją iš summary skambučio objekte. Taip pat pasiekiama skambučio puslapyje valdymo skydelyje
extracted_dataobjektas | nullStruktūrizuotas ištraukimo rezultatas su status, fields, evidence, verification, field_reasons ir schema_version. Kiekvienas ne null laukas turi tikslią struktūriškai patikrintą citatą (daugiausia 1 000 simbolių), taip pat kalbėtojo vaidmenį ir ėjimo indeksą; ilgesnės modelio grąžintos citatos atmetamos, o ne sutrumpinamos. Įrodymai yra null, kai laukas yra null. verified reiškia, kad kiekvienas kandidatas gavo lygiai vieną galiojantį nepriklausomą vertinimą. unavailable taip pat apima netaisyklingą arba dalinę tikrintojo išvestį; galiojantys daliniai vertinimai vis tiek taikomi, o kandidatai be vieno galiojančio vertinimo nustatomi į null. status yra completed, failed, exhausted, skipped arba skipped_recording_disabled; null, kai agentas neturėjo ištraukimo laukų
steps_tracemasyvasTik skambučiams, kurių agentas turi veiksmų arba perdavimų. Tvarka, kuria skambutis judėjo per juos: kiekvienas įrašas turi t_ms (milisekundės nuo skambučio pradžios), agent (agento raktas, a ir jo ID), step (veiksmo ID arba null, perduodant agentui be veiksmų) ir via (start, model, condition, on_enter arba handoff). Saugo tik ID ir laikus, todėl išlaikoma net kai įrašymas išjungtas
collected_valuesobjektasTik skambučiams, kurių agentas turi veiksmų arba perdavimų. Reikšmės, kurias agentas surinko savo veiksmuose, susietos pagal rinkimo lauko pavadinimą, taip pat <tool>_result kiekvieno veiksmo on_enter_tool rezultatui. Neįtraukiama, kai skambučio turinys neišsaugomas (įrašymas išjungtas)

Pabaigos priežastys

ReikšmėPrasmė
user_hangupNuotolinė šalis pirmoji nutraukė skambutį
ai_hangupAI sąmoningai baigė skambutį
ai_transferAI perdavė skambutį; nustatytas transfer_number
ai_warm_transferAI užbaigė šiltąjį perdavimą su dalyvavimu
returned_to_platformAI grąžino skambutį į jūsų kontaktų centrą: ji nutraukė skambutį ir, jei jų buvo, į SIP BYE įtraukė grąžinimo įrašo antraštes
voicemail_hangupAptiktas balso paštas, o skambutis baigtas pagal jūsų voicemail_action
max_durationSkambutis pasiekė maksimalią trukmės ribą: balso agento, paties skambučio arba 6 valandų platformos ribą. Jei AI arba skambinantysis baigia skambutį po įspėjimo apie laiko limitą, išlieka ai_hangup arba user_hangup
supersededSesiją pakeitė naujesnė
inbound_config_webhook_failedĮeinantis skambutis į numerį žiniatinklio kabliuko režimu: konfigūracijos žiniatinklio kabliukas negrąžino tinkamos konfigūracijos, todėl skambutis buvo baigtas prieš balso agentui atsiliepiant. status yra failed, o skambutis neapmokestinamas
outbound_queue_timeoutEilėje esantis skambutis 10 minučių laukė, kol atsiras galimybė rinkti numerį. status yra failed, nebuvo surinktas joks numeris, o skambutis neapmokestinamas
outbound_queue_canceledAtšaukėte eilėje esantį skambutį prieš jam renkant numerį. status yra failed, o skambutis neapmokestinamas
unknownNepavyko nustatyti baigimo priežasties

Transkripto formatas

Kiekvienas transcripts įrašas yra vienas pokalbio ėjimas. Vaidmenys yra user (skambinančiojo kalba), model (agento kalba ir įrankių iškvietimai), tool (įrankių rezultatai) ir system (skambučio įvykiai, pvz., kalbos perjungimai).

[
  {
    "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"] }
    }
  }
]
LaukasTipasAprašymas
roleeilutėuser, model, tool arba system
content_typeeilutėtext/plain kalbai; application/json įrankių iškvietimams, įrankių rezultatams ir sistemos įvykiams
contenteilutė | objektasKalbos tekstas arba pirmiau parodytas struktūrizuotas objektas. Įrankių iškvietimai: {"tool_call": name, "arguments": {…}}. Įrankių rezultatai: {"tool_name": name, "response": {…}}
start_ms, end_mssveikasis skaičiusPoslinkiai nuo skambučio pradžios, ms. Pateikiami, kai žinomas garso laikas
ttfa_mssveikasis skaičiusLaikas iki pirmojo garso model ėjimui, kai išmatuotas
audio_url, audio_urlseilutė / masyvasBaigiančio galioti pasirašyti URL ėjimo garso įrašui, kai įrašoma kiekvienam ėjimui

Visai struktūrizuotai ėjimų istorijai (su pertraukimo žymenimis, patvirtinimo raginimais ir neapdorotomis pozicijomis) naudokite GET /v1/calls/{call_id}/history.

Ankstesnės versijos naudingosios apkrovos skirtumai

Ankstesnės versijos vieno URL žiniatinklio kablio apvalkalas yra {"type": "telephony.complete" | "web.complete", "data": {…}} be event_id, o jo data skiriasi nuo galinio taško naudingosios apkrovos:

Ankstesnės versijos užbaigimo naudingoji apkrova taip pat turi agent_id ir agent_name.

  • Ėjimų masyvas yra history, o ne transcripts (ta pati ėjimo schema kaip pirmiau).
  • Laukų rinkinys yra neapdorota skambučio pabaigos ataskaita ir gali apimti papildomus vidinius laukus, kurių nėra pirmiau pateiktoje lentelėje — nežinomus laukus laikykite informaciniais.
  • Žiniatinklio skambučiai (direction: "web") nepateikia from_number / to_number ir prideda origin_domain.
  • Konstruktoriaus mikrofono bandomieji skambučiai ankstesnės versijos kelyje pateikiami kaip telephony.complete (galinio taško sistema juos susieja su web.complete).
  • Perdavimo koordinavimas: kai skambutis baigiasi perdavimu, ankstesnės versijos žiniatinklio kablys iškviečiamas sinchroniškai ir gali atsakyti {"transfer_ready": false}, kad nurodytų, jog perdavimo paskirties vieta nėra parengta. Bet koks kitas atsakymas (arba ankstesnės versijos žiniatinklio kablio nebuvimas) leidžia tęsti perdavimą. Galinio taško pristatymai tam niekada nenaudojami.

Pavyzdinė apdorojimo funkcija

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

Dažniausi naudojimo atvejai

CRM integracija

Išsaugokite kiekvieno skambučio transkriptą ir įrašo URL kartu su klientų įrašais.

Analitika

Siųskite transkriptus į duomenų srautą temų modeliavimui, CSAT signalų išskyrimui arba perdavimo rodiklio stebėjimui.

Kokybės peržiūra

Atidarykite skambučius QA įrankyje, kad juos peržiūrėtų žmonės, arba apdorokite juos savo vertinimo modeliu.

Pranešimai

Perduodant skambutį arba įvykus klaidai praneškite komandos nariui.


Susiję