ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Webhooks

telephony.complete / web.complete

Неблокирајући вебхук који се испоручује када се позив заврши, са транскриптом, URL-ом снимка и метрикама.

Догађај завршетка се покреће након завршетка сваког позива — долазне телефоније, одлазне телефоније, веб позива или тест позива (сесија микрофона у алату за израду). Он је неблокирајући: одговорите било којим кодом 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_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"
}
ПољеТипОпис
call_idintegerСтабилан у сваком догађају за овај позив
agent_idinteger | nullАгент који је обрадио позив, када је додељен
agent_namestring | nullАгент који је обрадио позив, када је додељен
directionstringinbound, outbound, web, test. Историјски терети могу садржати застареле вредности mic или widget
from_number, to_numberstringE.164. from_number је дословна вредност "web" за веб позиве и тест позиве
origin_domainstringСамо за веб/тест — извор странице на којој је виџет хостован (празно за mic сесије)
start_time, end_timetimestampISO 8601 UTC
duration_secondsinteger | nullИзведено из времена почетка и завршетка
statusstringcompleted или failed
end_reasonstringПогледајте табелу испод
answered_bystring | nullСамо за одлазне телефонске позиве (иначе није присутно): ко се јавио, human, voicemail, screener (помоћник за филтрирање позива), ivr (телефонски мени) или unknown. null када се нико није јавио, и увек null у догађајима migration.call.complete за одлазне позиве које је обрадила платформа са које прелазите. Исте вредности као у објекту позива
product, voicestringКонфигурација агента активна у тренутку позива
variablesobjectУлазне променљиве снимљене када је позив започет
unresolved_variablesarrayНазиви променљивих на које се конфигурација позива позива, али које нису достављене при почетку позива
transfer_numberstring | nullПоставља се када је позив преусмерен
scheduled_send_idstringСамо за позив упућен путем заказаног слања: идентификатор тог слања. Није присутно за сваки други позив
recording_urlstring | nullПотписани URL који истиче; преузмите га одмах. null када артефакт снимка није доступан
recording_stopped_attimestamp | nullКада је снимање заустављено пре завршетка позива; ништа након овог тренутка није у снимку. null када је снимање трајало до краја позива или позив није сниман
recording_stopped_reasonstring | nullЗашто је снимање рано заустављено. warm_transfer: зауставља се непосредно пре него што топли трансфер позове одредиште и остаје искључено чак и ако трансфер не успе и позивалац се врати агенту. Остале вредности сматрајте информативним; могу бити додате нове. null када је recording_stopped_at null
billable_minutesnumberНаплаћени минути, заокружени на најближу четвртину минута (инкременти од 15 секунди, минимум 0.25). Позиви директно на говорну пошту и даље овде пријављују стварне измерене минуте, али је наплата ограничена на један минут по стопи плана.
billing_total_centsinteger | nullUSD центи. null док је billing_pending true
billing_pendingbooleanПрисутно само као true за позив са обрачуном по потрошњи чија наплата још није измирена: позив са обрачуном по потрошњи наплаћује се неколико минута након завршетка, када стигне његова употреба, па су billable_minutes и billing_total_cents овде null, а наплата стиже у call.billed. Није присутно за сваки други позив
transcriptsarrayУноси транскрипта по потезу; може бити празно када транскрипт није доступан
summarystring | nullСажетак након позива написан једноставним језиком (две до четири реченице прозе, највише 2.000 знакова, написан на summary_language агента, у супротном на језику сажетака организације, а у супротном на језику позива: примарном језику агента, осим ако га позив није заменио) када агент има укључено Генеришите сажетак позива у одељку Подаци за прикупљање у градитељу агента (call_summary_enabled на Агенту) и генерисање је успело; у супротном null, укључујући позиве прекратке за сажимање, позиве без транскрипта и агенте са искљученим снимањем. Сажетак се генерише у истом кораку након позива као и издвајање, па подешавање Сачекајте издвојене податке пре слања веб-хука о завршетку позива (extraction_blocks_completion) одређује да ли овај догађај чека на њега: у режиму чекања сажетак је спреман пре слања овог догађаја (сам сажетак има највише 30 секунди у оквиру буџета корака од 75 секунди); када догађај не чека (never, или трансфер или повратак у ваш контакт центар у оквиру except_transfers), ово поље је null и сажетак се не шаље поново у call.data_extracted, па га касније прочитајте из summary у објекту позива. Доступно је и на страници позива на контролној табли
extracted_dataobject | nullРезултат структурираног издвајања са status, fields, evidence, verification, field_reasons и schema_version. Свако поље које није null садржи тачан структурно проверен цитат (највише 1.000 знакова), као и улогу говорника и индекс потеза; дужи цитати које врати модел се одбацују уместо да се скраћују. Доказ је null када је поље null. verified значи да је сваки кандидат добио тачно једну важећу независну пресуду. unavailable такође обухвата неисправан или делимичан излаз проверавача; важеће делимичне пресуде се и даље примењују, док се кандидати без једне важеће пресуде постављају на null. status је completed, failed, exhausted, skipped или skipped_recording_disabled; null када агент нема поља за издвајање
steps_tracearrayСамо за позиве чији агент има кораке или предаје. Редослед којим се позив кретао кроз њих: сваки унос има t_ms (милисекунде од почетка позива), agent (кључ агента, a плус његов ИД), step (ИД корака, или null при предаји агенту без корака) и via (start, model, condition, on_enter или handoff). Садржи само ИД-ове и времена, па се чува чак и када је снимање искључено
collected_valuesobjectСамо за позиве чији агент има кораке или предаје. Вредности које је агент прикупио у својим корацима, са кључем према називу поља за прикупљање, као и <tool>_result за резултат on_enter_tool сваког корака. Изостављено када се садржај позива не задржава (снимање је искључено)

Разлози завршетка

ВредностЗначење
user_hangupУдаљена страна је прва прекинула везу
ai_hangupAI је намерно завршио позив
ai_transferAI је пренео позив; transfer_number је подешен
ai_warm_transferAI је завршио топли пренос позива (уз присуство)
returned_to_platformAI је вратио позив у Ваш контакт центар: прекинуо је везу, са заглављима уноса за повратак у SIP BYE ако постоје
voicemail_hangupОткривена је говорна пошта и позив је завршен у складу са Вашим voicemail_action
max_durationПозив је достигао ограничење максималног трајања: ограничење агента, ограничење самог позива или ограничење платформе од 6 сати. Позив који AI или позивалац заврши након упозорења о временском ограничењу задржава ai_hangup или user_hangup
supersededСесија је замењена новијом
inbound_config_webhook_failedДолазни позив на број у режиму веб-куке: веб-кука за конфигурацију није вратила употребљиву конфигурацију, па је позив завршен пре него што је агент одговорио. status је failed и позив се не наплаћује
outbound_queue_timeoutПозив у реду је чекао 10 минута без могућности за бирање. status је failed, ништа није бирано и позив се не наплаћује
outbound_queue_canceledОтказали сте позив у реду пре бирања. status је failed и позив се не наплаћује
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"] }
    }
  }
]
ПољеТипОпис
roleнискаuser, model, tool или system
content_typeнискаtext/plain за говор; application/json за позиве алата, резултате алата и системске догађаје
contentниска | објекатТекст говора или структурисани објекат приказан изнад. Позиви алата: {"tool_call": name, "arguments": {…}}. Резултати алата: {"tool_name": name, "response": {…}}
start_ms, end_msцео бројПомераји од почетка позива, у мс. Присутни када је познато аудио-време
ttfa_msцео бројВреме до првог звука за потез model, када је измерено
audio_url, audio_urlsниска / низПотписани URL-ови са истеком за аудио снимак потеза, када се снима по потезу

За потпуно структурисану историју потеза (са ознакама прекида, упитима за потврду и изворним позицијама), користите GET /v1/calls/{call_id}/history.

Разлике у застарелом садржају

Застарели омотач веб-хука са једним URL-ом је {"type": "telephony.complete" | "web.complete", "data": {…}} без event_id, а његов data се разликује од садржаја крајње тачке:

Застарели садржај по завршетку такође садржи agent_id и agent_name.

  • Низ потеза се налази у history, а не у transcripts (иста шема потеза као изнад).
  • Скуп поља је изворни извештај на крају позива и може да садржи додатна интерна поља изван горње табеле — непозната поља третирајте као информативна.
  • Веб позиви (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 алату за људску проверу или их обрадите кроз сопствени модел за евалуацију.

Обавештења

Обавестите члана тима при преносу / неуспеху.


Повезано