Katalóg udalostí

Každé telo webhooku má pole type, ktorého hodnota je jeden z typov udalostí na tejto stránke. Keď sa prihlásite na odber koncového bodu, pole events musí obsahovať typy udalostí, ktoré chcete dostávať (alebo musí byť prázdne, ak chcete odoberať všetko).

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

• Doručenia na koncový bod sú vždy neblokujúce oznámenia s opakovanými pokusmi: odpovedzte ľubovoľným kódom 2xx; obálka obsahuje event_id na deduplikáciu.
• Blokujúce výmeny prebiehajú iba cez starší webhook s jednou URL: požiadavka na konfiguráciu telephony.incoming / web.incoming (čísla v režime webhooku a kľúče widgetu, č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í na drôte (kľúče 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é pre každý prichádzajúci hovor bez ohľadu na to, či je číslo nakonfigurované pre agenta alebo webhook. Čísla bez priradeného agenta navyše dostávajú blokujúcu požiadavku na konfiguráciu na staršom webhooku — úplnú schému požiadavky a 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. Neblokujúce. Zahŕňa prepis, 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ý pri doručení tejto udalosti; vzťahuje sa na vaše vlastné funkčné nástroje (nie na 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>"}.

web.incoming

Ekvivalent telephony.incoming pre webový kanál, 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ú pre každú webovú reláciu typu fire-and-forget. Publikovateľné kľúče v mode="webhook" navyše dostávajú blokujúcu požiadavku na konfiguráciu na staršom webhooku — táto blokujúca požiadavka má iný tvar (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 webhook 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ú origin_domain a publishable_key_prefix prázdne.

web.complete

Ekvivalent telephony.complete pre webový kanál, ktorý zahŕňa hovory webového widgetu (direction: "web") a testovacie hovory mikrofónu v nástroji na vytváranie (direction: "test"). Neblokujúce. Má rovnaký tvar údajov ako telephony.complete, navyše s origin_domain, pričom from_number je nastavené na "web".

web.tool

Ekvivalent telephony.tool pre webový kanál. data obsahuje origin_domain namiesto from_number / to_number.

Hlasové udalosti

Vytvorenie 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 koncový bod detailu klonu.

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 dosiahne trvalé zlyhanie.

{
  "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 pre hovor dokončí spustenie hodnotenia AI. 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"
}

issue.reported

Odosiela sa pri vytvorení hlásenia problému — buď ho používateľ odošle z dashboardu (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"
}

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úce. Je užitočné na prepojenie dávkových spustení CI so systémami chatu alebo 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 výstrah

alert.triggered

Odosiela sa, keď pravidlo výstrahy s povoleným kanálom Doručovať do webhookov vývojára prekročí svoj prah. Neblokujúce. Pravidlo sa spustí raz a potom rešpektuje svoju ochrannú lehotu, takže pretrvávajúce prekročenie vytvorí jednu udalosť za každé okno ochrannej lehoty.

{
  "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, ochranných lehotách a kanáloch e-mailu / Slack nájdete v príručke k výstrahám.

Súvisiace