Katalóg udalostí

Všetky typy udalostí webhookov, ktoré ThunderPhone odosiela.

Každé telo webhooku má pole type, ktorého hodnota je jedným z typov udalostí na tejto stránke. Keď sa prihlásite na odber koncového bodu, pole events musí obsahovať požadované typy udalostí (alebo byť prázdne, ak chcete odoberať všetko — okrem udalostí pre jednotlivé ťahy telephony.turn / web.turn, ktoré sa doručujú iba koncovým bodom, ktoré ich výslovne uvádzajú).

Tieto udalosti sa doručujú dvoma spôsobmi:

• Doručenia do koncových bodov sú vždy neblokujúce oznámenia s opakovanými pokusmi: odpovedzte ľubovoľným stavom 2xx; obálka obsahuje event_id na deduplikáciu.
• Blokujúce výmeny prebiehajú iba v staršom webhooku s jedinou URL: požiadavka na konfiguráciu telephony.incoming / web.incoming (čísla v režime webhooku a kľúče widgetov, časový limit 10 s) a odoslanie nástroja v režime webhooku. Vaša odpoveď ovplyvňuje prebiehajúci hovor.

Príklady payloadov nižšie zobrazujú obálku koncového bodu v poradí prenosu (kľúče sú zoradené abecedne: data, event_id, type); staršie doručenia obsahujú rovnaké data bez event_id.

Udalosti hovorov#

telephony.incoming#

Odosiela sa, keď prichádzajúci hovor dorazí na jedno z vašich telefónnych čísel. Doručenia na koncový bod sú notifikácie typu fire-and-forget odosielané pri každom prichádzajúcom hovore bez ohľadu na to, či je číslo nakonfigurované pre agenta alebo webhook. Čísla bez priradeného agenta navyše dostanú blokujúcu konfiguračnú požiadavku na staršom webhooku — úplnú schému požiadavky / odpovede nájdete v telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

Odosiela sa po skončení prichádzajúceho alebo odchádzajúceho telefonického hovoru. Neblokuje. Obsahuje prepis, adresu URL nahrávky, ak je k dispozícii, a súhrn fakturácie. Schému údajov nájdete v telephony.complete / web.complete.

telephony.tool#

Odosiela sa po tom, ako telefonický hovor vyvolá funkčný nástroj. Neblokujúca notifikácia auditu — nástroj už bol vykonaný v čase doručenia tejto udalosti; zahŕňa vaše vlastné funkčné nástroje (nie vstavané nástroje, nástroje databázy znalostí, pripojenia aplikácií ani nástroje MCP).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response je výsledok vykonania: pri úspechu {"status": <http status>, "response": <your endpoint's JSON>} alebo pri zlyhaní {"status": <status>, "error": "<message>"}.

telephony.turn#

Odosiela sa počas telefonického hovoru, keď prebieha, raz pre každý úsek obsahujúci reč v okamihu jeho vzniku — hovorené dokončenia agenta a prepísané úseky volajúceho. Umožňuje sledovať živú konverzáciu prostredníctvom bežných webhookov namiesto dopytovania GET /v1/calls/{call_id}/transcript. Neblokuje.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

Webový ekvivalent telephony.incoming, odosielaný pri spustení relácie webového widgetu alebo testovacieho hovoru mikrofónu v nástroji na vytváranie. Doručenia na koncový bod sú notifikácie typu fire-and-forget pre každú webovú reláciu. Publikovateľné kľúče v režime mode="webhook" navyše dostanú blokujúcu konfiguračnú požiadavku na staršom webhooku — táto blokujúca požiadavka má odlišnú štruktúru (origin_domain, publishable_key_prefix; bez telefónnych čísel). Pozrite si telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number má vždy doslovnú hodnotu "web". Pri reláciách widgetu v režime webhooku je to_number prázdne (číslo agenta relácie sa priradí po konfigurácii); pri testovacích hovoroch mikrofónu v nástroji na vytváranie sú polia origin_domain a publishable_key_prefix prázdne.

web.complete#

Webový ekvivalent telephony.complete, zahŕňajúci hovory webového widgetu (direction: "web") a testovacie hovory mikrofónu v nástroji na vytváranie (direction: "test"). Neblokuje. Má rovnakú štruktúru údajov ako telephony.complete, navyše s origin_domain, pričom from_number je nastavené na "web".

web.tool#

Webový ekvivalent telephony.tool. Objekt data obsahuje origin_domain namiesto from_number / to_number.

web.turn#

Webový ekvivalent telephony.turn, zahŕňajúci hovory webového widgetu a testovacie hovory mikrofónu v nástroji na vytváranie. Má rovnakú štruktúru údajov, pričom obsahuje origin_domain namiesto from_number / to_number. Rovnako ako telephony.turn vyžaduje explicitné prihlásenie na odber — nikdy sa nedoručuje prostredníctvom prázdneho poľa events.

Hlasové udalosti#

Vytváranie vlastného hlasu prebieha asynchrónne. Tieto neblokujúce udalosti vám umožňujú reagovať na konečný výsledok namiesto pravidelného dopytovania sa na endpoint podrobností klonu.

voice.ready a voice.failed sa doručujú iba na endpoint pre celú organizáciu s events: []. Nemožno ich vybrať ako explicitné filtre udalostí.

voice.ready#

Odosiela sa, keď vlastný hlas dokončí spracovanie a možno ho priradiť agentovi.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed#

Odosiela sa, keď spracovanie vlastného hlasu skončí trvalým zlyhaním.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Udalosti kvality#

call.graded#

Odosiela sa vždy, keď sa dokončí spustenie hodnotenia AI pre hovor. Neblokujúce.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Odosiela sa vždy, keď sa úspešne dokončí extrakcia štruktúrovaných údajov vrátane neskorého opakovania po telephony.complete / web.complete alebo manuálneho opätovného spustenia prostredníctvom POST /v1/calls/{call_id}/extract. Neblokujúce.

V režime blokujúcej extrakcie udalosť dokončenia zvyčajne nečaká dlhšie než 75-sekundový limit extrakcie. Ak sa proces pracovníka extrakcie stratí, produkčné dokončovacie spracovanie (každých päť minút) uvoľní dokončenie, ktorého blocking_deadline_at uplynul, skôr než spustí ďalší pokus o extrakciu. Neskorší úspech sa doručí samostatne ako táto udalosť.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "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..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Odosiela sa raz, keď kampaň prejde zo stavu running do stavu completed, či už sa skončil jej harmonogram alebo všetky kontakty dosiahli koncové stavy. Opakované pokusy vykonávateľa neodošlú ďalšiu udalosť. Táto udalosť životného cyklu na úrovni organizácie sa doručuje iba koncovým bodom v rozsahu organizácie, nie koncovým bodom v rozsahu agenta. Neblokujúce.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Štyri počty výsledkov sa navzájom neprekrývajú a ich súčet sa rovná contacts_total: completed obsahuje úspešné kontakty; no_answer obsahuje neúspešné alebo vyčerpané kontakty v koncovom stave, ktorých konečným výsledkom bola žiadna odpoveď; failed obsahuje všetky ostatné neúspešné alebo vyčerpané kontakty v koncovom stave; a remaining obsahuje čakajúce, naplánované alebo práve volané kontakty. Kontakt čakajúci na opakovanie je remaining, aj keď jeho posledný pokus skončil bez odpovede. Prebiehajúce hovory sa zosúladia pred jednorazovým snímkom dokončenia. started_at je nakonfigurovaný začiatok kampane alebo čas vytvorenia kampane, ak nebol nakonfigurovaný začiatok.

issue.reported#

Odosiela sa pri vytvorení hlásenia problému — buď ho používateľ vytvorí z ovládacieho panela (source: "user"), alebo ho automaticky vytvorí hodnotenie hovoru (source: "system"). Neblokujúce.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

issue.escalated#

Odosiela sa, keď sa vzor problému odošle do ThunderPhone na kontrolu zamestnancami: po výbere možnosti Nahlásiť ThunderPhone, alebo keď funkcia Opraviť pomocou AI nedokáže potvrdiť opravu na strane zákazníka a problém automaticky presmeruje. Túto udalosť prijímajú iba koncové body pre celú organizáciu.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

Toto je upozornenie, nie balík dôkazov. Na prepojenie so vzorom problému použite cluster_id. Pozrite si Nahlásiť ThunderPhone.

Udalosti testovacích hovorov#

test-call.completed#

Odosiela sa, keď spustenie testovacieho hovoru dosiahne konečný stav — completed alebo failed vrátane spustení, ktoré zlyhali pri spustení a nikdy nevytvorili hovor. Neblokujúca udalosť. Užitočné na prepojenie dávkových spustení CI so systémami chatu a upozornení.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Udalosti upozornení#

alert.triggered#

Odosiela sa, keď pravidlo upozornenia s povoleným kanálom Doručovať do webhookov vývojára prekročí svoj prah. Neblokujúca udalosť. Pravidlo sa spustí raz a potom dodržiava interval ochladenia, takže pretrvávajúce prekročenie vytvorí jednu udalosť za každé okno ochladenia.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Informácie o vytváraní pravidiel, metrikách, intervaloch ochladenia a kanáloch e-mailu / Slack nájdete v príručke Upozornenia.

Súvisiace#