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_idцяло числоСтабилен за всяко събитие за това обаждане
agent_idцяло число | nullАгентът, обработил обаждането, когато е бил назначен такъв
agent_nameниз | nullАгентът, обработил обаждането, когато е бил назначен такъв
directionнизinbound, outbound, web, test. Историческите полезни товари може да съдържат остарели стойности mic или widget
from_number, to_numberнизE.164. from_number е буквалната стойност "web" за уеб обаждания и тестови обаждания
origin_domainнизСамо за уеб/тест — произходът на страницата, която хоства уиджета (празно за сесии с микрофон)
start_time, end_timeвремеви отпечатъкISO 8601 UTC
duration_secondsцяло число | nullИзведено от началото/края
statusнизcompleted или failed
end_reasonнизВижте таблицата по-долу
answered_byниз | nullСамо за изходящи телефонни обаждания (иначе липсва): кой е отговорил — human, voicemail, screener (асистент за филтриране на обаждания), ivr (телефонно меню) или unknown. null, когато никой не е отговорил, и винаги null в събития migration.call.complete за изходящи обаждания, обработени от платформата, от която мигрирате. Същите стойности като в обекта за обаждане
product, voiceнизКонфигурацията на агента, действаща към момента на обаждането
variablesобектВходни променливи, заснети в момента на започване на обаждането
unresolved_variablesмасивИмена на променливи, посочени от конфигурацията на обаждането, но непредоставени при започването му
transfer_numberниз | nullЗадава се, когато обаждането е прехвърлено
scheduled_send_idнизСамо при обаждане, извършено чрез планирано изпращане: идентификаторът на това изпращане. Липсва при всяко друго обаждане
recording_urlниз | nullПодписан URL адрес с изтичащ срок; изтеглете го своевременно. null, когато няма наличен артефакт на запис
recording_stopped_atвремеви отпечатък | nullКога записът е бил спрян преди края на обаждането; нищо след този момент не присъства в записа. null, когато записът е продължил до края на обаждането или обаждането не е било записано
recording_stopped_reasonниз | nullЗащо записът е спрял по-рано. warm_transfer: записът спира непосредствено преди топло прехвърляне да се обади на целевия номер и остава изключен дори ако прехвърлянето не успее и обаждащият се се върне при агента. Третирайте другите стойности като информационни; може да бъдат добавени още. null, когато recording_stopped_at е null
billable_minutesчислоТаксувани минути, закръглени до най-близката четвърт минута (интервали от 15 секунди, минимум 0.25). Обажданията, насочени директно към гласова поща, все още отчитат тук действителните си измерени минути, но таксата е ограничена до една минута по тарифата на плана.
billing_total_centsцяло число | nullАмерикански центове. null, докато billing_pending е true
billing_pendingбулева стойностПрисъства само като true при измервано обаждане, чиято такса все още не е уредена: измерваното обаждане се таксува няколко минути след приключването му, след като потреблението му бъде отчетено, така че billable_minutes и billing_total_cents тук са null, а таксата пристига в call.billed. Липсва при всяко друго обаждане
transcriptsмасивЗаписи в транскрипцията за всеки ход; може да е празен, когато транскрипция не е налична
summaryниз | nullРезюме след обаждането на разбираем език (две до четири изречения проза, най-много 2 000 знака, написано на summary_language на агента, иначе на езика за резюмета на организацията, иначе на езика на обаждането: основния език на агента, освен ако обаждането не го е заменило), когато за агента е включено Генериране на резюме на обаждането в Данни за събиране в създателя на агента (call_summary_enabled в Агент) и генерирането е успешно; в противен случай null, включително за обаждания, които са твърде кратки за обобщаване, обаждания без транскрипция и агенти с изключен запис. Резюмето се генерира в същата стъпка след обаждането като извличането, затова настройката Изчакване на извлечените данни преди изпращане на уебкуката за приключено обаждане (extraction_blocks_completion) определя дали това събитие го изчаква: в режим на изчакване резюмето е готово преди изпращането на това събитие (самото резюме получава най-много 30 секунди в рамките на 75-секундния бюджет на стъпката); когато събитието не изчаква (never, или прехвърляне, или връщане към вашия контактен център при except_transfers), това поле е null и резюмето не се изпраща отново в call.data_extracted, затова го прочетете по-късно от summary в обекта за обаждане. Налично е и на страницата на обаждането в таблото
extracted_dataобект | nullРезултат от структурирано извличане с status, fields, evidence, verification, field_reasons и schema_version. Всяко ненулево поле съдържа точния структурно проверен цитат (най-много 1 000 знака), както и ролята на говорещия и индекса на хода му; по-дългите цитати, върнати от модела, се отхвърлят вместо да бъдат съкратени. Доказателството е null, когато полето е null. verified означава, че всеки кандидат е получил точно едно валидно независимо заключение. unavailable обхваща и неправилен или частичен изход от проверяващия механизъм; валидните частични заключения все пак се прилагат, докато кандидатите без едно валидно заключение се зануляват. status е completed, failed, exhausted, skipped или skipped_recording_disabled; null, когато агентът няма полета за извличане
steps_traceмасивСамо при обаждания, чийто агент има стъпки или предавания. Редът, в който обаждането е преминало през тях: всеки запис съдържа t_ms (милисекунди от началото на обаждането), agent (ключът на агента, a плюс неговия идентификатор), step (идентификаторът на стъпката или null при предаване към агент без стъпки) и via (start, model, condition, on_enter или handoff). Съдържа само идентификатори и времена, затова се запазва дори когато записът е изключен
collected_valuesобектСамо при обаждания, чийто агент има стъпки или предавания. Стойностите, които агентът е събрал в стъпките си, въведени по име на поле за събиране, плюс <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.

Разлики в наследения payload

Наследеният webhook контейнер с един URL е {"type": "telephony.complete" | "web.complete", "data": {…}} без event_id, а неговият data се различава от payload на крайната точка:

Наследеният payload при завършване съдържа също agent_id и agent_name.

  • Масивът с ходове е в history, а не в transcripts (същата схема на ходовете като по-горе).
  • Наборът от полета е необработеният отчет в края на обаждането и може да включва допълнителни вътрешни полета извън таблицата по-горе — третирайте непознатите полета като информативни.
  • Уеб обажданията (direction: "web") пропускат from_number / to_number и добавят origin_domain.
  • Тестовите обаждания с микрофон в конструктора се отчитат като telephony.complete по наследения път (системата на крайната точка ги преобразува в web.complete).
  • Координация на прехвърлянето: когато обаждане завърши с прехвърляне, наследеният webhook се извиква синхронно и може да върне {"transfer_ready": false}, за да сигнализира, че целта на прехвърлянето не е готова. Всеки друг отговор (или липсата на наследен webhook) позволява прехвърлянето да продължи. Доставките до крайната точка никога не се вземат предвид за това.

Примерен обработчик

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 сигнали или наблюдение на процента прехвърлени обаждания.

Преглед на качеството

Отваряйте обажданията в инструмент за осигуряване на качеството за човешки преглед или ги обработвайте чрез собствения си модел за оценяване.

Известия

Известявайте член на екипа при прехвърляне / неуспех.


Свързано