ThunderPhone 2.0 ఇప్పుడు అందుబాటులో ఉంది.మీరే ప్రారంభించవచ్చు—నిమిషానికి 2¢ నుంచి.ప్రకటనను చదవండి

Webhooks

telephony.complete / web.complete

ట్రాన్స్‌క్రిప్ట్, రికార్డింగ్ URL మరియు మెట్రిక్‌లతో కాల్ ముగిసినప్పుడు పంపబడే నాన్-బ్లాకింగ్ వెబ్‌హుక్.

ప్రతి కాల్ ముగిసిన తర్వాత ఒక completion ఈవెంట్ ట్రిగ్గర్ అవుతుంది — ఇన్‌బౌండ్ టెలిఫోనీ, అవుట్‌బౌండ్ టెలిఫోనీ, వెబ్ కాల్ లేదా టెస్ట్ కాల్ (బిల్డర్ మైక్ సెషన్). ఇది బ్లాకింగ్ కానిది: ఏదైనా 2xxతో స్పందించండి.

ఈవెంట్ రెండు మార్గాల్లో పంపబడుతుంది:

అభ్యర్థన పేలోడ్ (ఎండ్‌పాయింట్ డెలివరీలు)

{
  "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_url": "https://storage.example.com/…",
    "start_time": "2026-04-20T18:24:10.113Z",
    "status": "completed",
    "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"
}
ఫీల్డ్రకంవివరణ
call_idintegerఈ కాల్‌కు సంబంధించిన ప్రతి ఈవెంట్‌లో స్థిరంగా ఉంటుంది
agent_idinteger | nullకేటాయించబడినప్పుడు, కాల్‌ను నిర్వహించిన ఏజెంట్
agent_namestring | nullకేటాయించబడినప్పుడు, కాల్‌ను నిర్వహించిన ఏజెంట్
directionstringinbound, outbound, web, test. చారిత్రక పేలోడ్‌లలో లెగసీ mic లేదా widget విలువలు ఉండవచ్చు
from_number, to_numberstringE.164. వెబ్ కాల్‌లు మరియు టెస్ట్ కాల్‌లకు from_number అనేది అక్షరార్థంగా "web" ఉంటుంది
origin_domainstringవెబ్/టెస్ట్‌కు మాత్రమే — విడ్జెట్‌ను హోస్ట్ చేసిన పేజీ ఆరిజిన్ (మైక్ సెషన్‌లకు ఖాళీగా ఉంటుంది)
start_time, end_timetimestampISO 8601 UTC
duration_secondsinteger | nullప్రారంభం/ముగింపు సమయాల నుంచి పొందబడుతుంది
statusstringcompleted లేదా failed
end_reasonstringదిగువ పట్టికను చూడండి
product, voicestringకాల్ సమయంలో అమల్లో ఉన్న ఏజెంట్ కాన్ఫిగరేషన్
variablesobjectకాల్ ప్రారంభమైనప్పుడు స్నాప్‌షాట్ చేసిన ఇన్‌పుట్ వేరియబుల్స్
unresolved_variablesarrayకాల్ కాన్ఫిగరేషన్ సూచించినప్పటికీ కాల్ ప్రారంభంలో అందించబడని వేరియబుల్ పేర్లు
transfer_numberstring | nullకాల్ బదిలీ చేయబడినప్పుడు సెట్ అవుతుంది
recording_urlstring | nullగడువు ముగిసే సంతకం చేసిన URL; వెంటనే డౌన్‌లోడ్ చేయండి. రికార్డింగ్ ఆర్టిఫాక్ట్ అందుబాటులో లేనప్పుడు null
billable_minutesnumberబిల్ చేయబడిన నిమిషాలు, సమీప క్వార్టర్ నిమిషానికి రౌండ్ చేయబడతాయి (15-సెకన్ల ఇంక్రిమెంట్లు, కనిష్ఠం 0.25). నేరుగా వాయిస్‌మెయిల్‌కు వెళ్లే కాల్‌లు కూడా వాటి వాస్తవ మీటర్ చేసిన నిమిషాలను ఇక్కడ నివేదిస్తాయి, కానీ ఛార్జీ ప్లాన్ రేటు వద్ద ఒక నిమిషానికి పరిమితం చేయబడుతుంది.
billing_total_centsintegerUSD సెంట్లు
transcriptsarrayప్రతి టర్న్‌కు ట్రాన్స్‌క్రిప్ట్ ఎంట్రీలు; ట్రాన్స్‌క్రిప్ట్ అందుబాటులో లేనప్పుడు ఖాళీగా ఉండవచ్చు
extracted_dataobject | nullstatus, fields, evidence, verification, field_reasons, మరియు schema_versionతో కూడిన నిర్మిత ఎక్స్‌ట్రాక్షన్ ఫలితం. ప్రతి null కాని ఫీల్డ్‌లో ఖచ్చితంగా నిర్మాణాత్మకంగా తనిఖీ చేసిన కోట్ (గరిష్ఠంగా 1,000 అక్షరాలు), అలాగే దాని స్పీకర్ పాత్ర మరియు టర్న్ ఇండెక్స్ ఉంటాయి; మోడల్ తిరిగి ఇచ్చిన పొడవైన కోట్‌లను కత్తిరించకుండా తిరస్కరిస్తారు. ఫీల్డ్ null అయినప్పుడు ఎవిడెన్స్ null అవుతుంది. verified అంటే ప్రతి అభ్యర్థికి ఖచ్చితంగా ఒక చెల్లుబాటు అయ్యే స్వతంత్ర తీర్పు అందిందని అర్థం. తప్పుగా రూపొందిన లేదా పాక్షిక వెరిఫైయర్ అవుట్‌పుట్ కూడా unavailableలోకి వస్తుంది; చెల్లుబాటు అయ్యే పాక్షిక తీర్పులు వర్తిస్తాయి, అయితే ఒక చెల్లుబాటు అయ్యే తీర్పు లేని అభ్యర్థులు null చేయబడతారు. status విలువ completed, failed, exhausted, skipped, లేదా skipped_recording_disabled; ఏజెంట్‌కు ఎక్స్‌ట్రాక్షన్ ఫీల్డ్‌లు లేనప్పుడు null

ముగింపు కారణాలు

విలువఅర్థం
user_hangupరిమోట్ పక్షం ముందుగా కాల్‌ను ముగించింది
ai_hangupAI ఉద్దేశపూర్వకంగా కాల్‌ను ముగించింది
ai_transferAI కాల్‌ను బదిలీ చేసింది; transfer_number సెట్ చేయబడుతుంది
ai_warm_transferAI వార్మ్ (అటెండెడ్) బదిలీని పూర్తి చేసింది
voicemail_hangupవాయిస్‌మెయిల్ గుర్తించబడింది మరియు మీ voicemail_action ప్రకారం కాల్ ముగిసింది
max_durationకాల్ గరిష్ఠ వ్యవధి పరిమితిని చేరుకుంది
supersededసెషన్‌ను కొత్తది భర్తీ చేసింది
unknownముగింపు కారణాన్ని నిర్ధారించలేకపోయాము

ట్రాన్స్‌క్రిప్ట్ ఫార్మాట్

transcriptsలోని ప్రతి ఎంట్రీ ఒక సంభాషణ టర్న్. పాత్రలు user (కాలర్ మాటలు), model (ఏజెంట్ మాటలు మరియు టూల్ కాల్‌లు), tool (టూల్ ఫలితాలు), మరియు system (భాష మార్పులు వంటి కాల్ ఈవెంట్‌లు).

[
  {
    "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"] }
    }
  }
]
ఫీల్డ్రకంవివరణ
rolestringuser, model, tool, లేదా system
content_typestringమాటల కోసం text/plain; టూల్ కాల్‌లు, టూల్ ఫలితాలు, మరియు సిస్టమ్ ఈవెంట్‌ల కోసం application/json
contentstring | objectమాటల టెక్స్ట్ లేదా పైన చూపిన నిర్మాణాత్మక ఆబ్జెక్ట్. టూల్ కాల్‌లు: {"tool_call": name, "arguments": {…}}. టూల్ ఫలితాలు: {"tool_name": name, "response": {…}}
start_ms, end_msintegerకాల్ ప్రారంభం నుంచి ఆఫ్‌సెట్‌లు, ms. ఆడియో టైమింగ్ తెలిసినప్పుడు ఉంటుంది
ttfa_msintegerకొలిచినప్పుడు, model టర్న్ కోసం మొదటి ఆడియో వరకు సమయం
audio_url, audio_urlsstring / arrayప్రతి టర్న్‌కు రికార్డ్ చేసినప్పుడు, ఆ టర్న్ ఆడియో కోసం గడువు ముగిసే సంతకంతో కూడిన URLలు

ఇంటరప్షన్ మార్కర్‌లు, అంగీకార promptలు, మరియు రా పొజిషన్‌లతో పూర్తి నిర్మాణాత్మక టర్న్ హిస్టరీ కోసం, GET /v1/calls/{call_id}/history ఉపయోగించండి.

లెగసీ పేలోడ్ తేడాలు

లెగసీ సింగిల్-URL వెబ్‌హుక్ ఎన్వలప్ {"type": "telephony.complete" | "web.complete", "data": {…}}; ఇందులో event_id ఉండదు, మరియు దాని data, ఎండ్‌పాయింట్ పేలోడ్‌కు భిన్నంగా ఉంటుంది:

లెగసీ కంప్లీషన్ పేలోడ్‌లో agent_id మరియు agent_name కూడా ఉంటాయి.

  • టర్న్ అరే transcripts కింద కాకుండా history కింద ఉంటుంది (పైన ఉన్నదే టర్న్ స్కీమా).
  • ఫీల్డ్ సెట్ అనేది కాల్ ముగింపు సమయంలోని రా రిపోర్ట్; ఇందులో పైన ఉన్న పట్టికకు మించిన అదనపు అంతర్గత ఫీల్డ్‌లు ఉండవచ్చు — తెలియని ఫీల్డ్‌లను సమాచారంగా పరిగణించండి.
  • వెబ్ కాల్‌లు (direction: "web") from_number / to_numberను మినహాయిస్తాయి మరియు origin_domainను జోడిస్తాయి.
  • బిల్డర్ మైక్ టెస్ట్ కాల్‌లు లెగసీ పాత్‌లో telephony.completeగా రిపోర్ట్ అవుతాయి (ఎండ్‌పాయింట్ సిస్టమ్ వాటిని web.completeకు మ్యాప్ చేస్తుంది).
  • ట్రాన్స్‌ఫర్ సమన్వయం: ట్రాన్స్‌ఫర్ సమయంలో కాల్ ముగిసినప్పుడు, లెగసీ వెబ్‌హుక్‌ను సింక్రోనస్‌గా కాల్ చేస్తారు మరియు హ్యాండ్‌ఆఫ్ టార్గెట్ సిద్ధంగా లేదని సూచించడానికి అది {"transfer_ready": false}తో ప్రతిస్పందించవచ్చు. ఇతర ఏ ప్రతిస్పందనైనా (లేదా లెగసీ వెబ్‌హుక్ లేకపోయినా) ట్రాన్స్‌ఫర్ కొనసాగడానికి అనుమతిస్తుంది. దీని కోసం ఎండ్‌పాయింట్ డెలివరీలను ఎప్పుడూ సంప్రదించరు.

ఉదాహరణ హ్యాండ్లర్

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

సాధారణ వినియోగ సందర్భాలు

CRM ఇంటిగ్రేషన్

ప్రతి కాల్ ట్రాన్స్‌క్రిప్ట్ మరియు రికార్డింగ్ URLను మీ కస్టమర్ రికార్డులతో పాటు నిల్వ చేయండి.

విశ్లేషణలు

టాపిక్ మోడలింగ్, CSAT సిగ్నల్ ఎక్స్‌ట్రాక్షన్ లేదా ట్రాన్స్‌ఫర్-రేట్ పర్యవేక్షణ కోసం ట్రాన్స్‌క్రిప్ట్‌లను పైప్‌లైన్‌కు స్ట్రీమ్ చేయండి.

నాణ్యత సమీక్ష

మానవ సమీక్ష కోసం కాల్‌లను QA టూల్‌లో తెరవండి లేదా వాటిని మీ స్వంత మూల్యాంకన మోడల్ ద్వారా అమలు చేయండి.

నోటిఫికేషన్లు

ట్రాన్స్‌ఫర్ / వైఫల్యంపై మానవ సహచరుడిని ట్రిగ్గర్ చేయండి.


సంబంధితవి