Katalog událostí

Každé tělo webhooku obsahuje pole type, jehož hodnota je jedním z typů událostí na této stránce. Když se přihlásíte k odběru koncového bodu, pole events musí obsahovat požadované typy událostí (nebo být prázdné pro odběr všech událostí). Tyto události se doručují dvěma způsoby:

Doručení na koncový bod jsou vždy neblokující oznámení s opakovanými pokusy: odpovězte libovolným kódem 2xx; obálka obsahuje event_id pro deduplikaci.
Blokující výměny probíhají pouze ve starším webhooku s jedinou URL: požadavek na konfiguraci telephony.incoming / web.incoming (čísla v režimu webhooku a klíče widgetu, časový limit 10 s) a odesílání nástrojů v režimu webhooku. Vaše odpověď ovlivňuje probíhající hovor.

Níže uvedené příklady datových částí ukazují obálku koncového bodu v pořadí přenášeném po síti (klíče jsou seřazeny abecedně: data, event_id, type); starší doručení obsahují stejné data bez event_id.

Události hovorů

`telephony.incoming`

Odesílá se, když příchozí hovor dorazí na jedno z vašich telefonních čísel. Doručení na endpoint jsou oznámení typu fire-and-forget odesílaná pro každý příchozí hovor, ať je číslo nakonfigurováno pro agenta nebo webhook. Čísla bez přiřazeného agenta navíc obdrží blokující požadavek na konfiguraci ve starším webhooku — úplné schéma požadavku / odpovědi najdete 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`

Odesílá se po ukončení příchozího nebo odchozího telefonního hovoru. Neblokující. Zahrnuje přepis, URL záznamu, pokud je k dispozici, a souhrn účtování. Schéma datové části najdete v telephony.complete / web.complete.

`telephony.tool`

Odesílá se poté, co telefonní hovor vyvolá funkční nástroj. Neblokující oznámení pro audit — nástroj již byl spuštěn při doručení této události; zahrnuje vaše vlastní funkční nástroje (nikoli integrované nástroje, nástroje znalostní báze, připojení aplikací 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ýsledek spuštění: {"status": <http status>, "response": <your endpoint's JSON>} při úspěchu nebo {"status": <status>, "error": "<message>"} při selhání.

`web.incoming`

Ekvivalent telephony.incoming pro webový kanál, odesílaný při spuštění relace webového widgetu nebo testovacího hovoru mikrofonu v editoru. Doručení na endpoint jsou pro každou webovou relaci typu fire-and-forget. Publikovatelné klíče v režimu mode="webhook" navíc obdrží blokující požadavek na konfiguraci ve starším webhooku — tento blokující požadavek má jinou strukturu (origin_domain, publishable_key_prefix; bez telefonních čísel). Viz 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 doslovnou hodnotu "web". Pro relace widgetu v režimu webhooku je to_number prázdné (číslo agenta relace je přiřazeno po konfiguraci); pro testovací hovory mikrofonu v editoru jsou origin_domain a publishable_key_prefix prázdné.

`web.complete`

Ekvivalent telephony.complete pro webový kanál, zahrnující hovory webového widgetu (direction: "web") a testovací hovory mikrofonu v editoru (direction: "test"). Neblokující. Má stejnou strukturu datové části jako telephony.complete, navíc s origin_domain, přičemž from_number je nastaveno na "web".

Ve starším webhooku s jedinou URL se testovací hovory mikrofonu v editoru historicky uvádějí jako telephony.complete — pouze hovory s direction: "web" zde používají typ web.complete. Systém endpointů mapuje webové i testovací hovory na web.*. Historické datové části mohou obsahovat starší hodnoty direction widget nebo mic.

`web.tool`

Ekvivalent telephony.tool pro webový kanál. data obsahuje origin_domain namísto from_number / to_number.

Hlasové události

Vytváření vlastního hlasu probíhá asynchronně. Tyto neblokující události vám umožňují reagovat na konečný výsledek namísto dotazování na endpoint s podrobnostmi klonu.

`voice.ready`

Odesílá se, když vlastní hlas dokončí zpracování a lze jej přiřadit 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`

Odesílá se, když zpracování vlastního hlasu skončí trvalým selhání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"
}

Pole	Typ	Popis
`voice.id`	string	Veřejné ID vlastního hlasu
`voice.name`	string	Hodnota hlasu agenta ve formátu `custom:<public_id>`
`voice.display_name`	string	Název hlasu určený pro organizaci
`voice.language`	string	Kód jediného jazyka klonu
`voice.gender`	string	`male`, `female` nebo prázdný řetězec
`voice.status`	string	`ready` pro `voice.ready`; `failed` pro `voice.failed`
`voice.failure_reason`	string	Při úspěchu prázdné; při selhání podrobnosti o selhání zpracování
`voice.created_at`, `voice.updated_at`	timestamp	Časová razítka ISO 8601
`reason`	string	Podrobnosti o selhání; přítomno pouze u `voice.failed`

Události kvality

`call.graded`

Odesílá se po dokončení běhu hodnocení AI pro hovor. Neblokující.

{
  "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"
}

Pole	Typ	Popis
`grade.id`	integer	ID hodnocení
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` nebo `no_conversation`
`grade.summary`	string	Jednoodstavcové shrnutí
`grade.detected_issues`	array	Řetězce problémů nalezených hodnotitelem
`grade.status`	string	Vždy `completed` — odesílají se pouze dokončené běhy
`grade.grader_model`	string	Hodnotitel, který vytvořil výsledek (např. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Hovor lze hodnotit více než jednou — po rychlém heuristickém hodnocení často následuje úplné hodnocení modelem, jakmile je k dispozici nahrávka, a je možné i ruční přehodnocení. Každý dokončený běh odešle vlastní událost call.graded; za rozhodující považujte nejnovější hodnotu graded_at.

`issue.reported`

Odesílá se při vytvoření hlášení problému — buď jej uživatel odešle z ovládacího panelu (source: "user"), nebo je automaticky vytvořeno hodnocením hovoru (source: "system"). Neblokující.

{
  "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"
}

Pole	Typ	Popis
`issue_report.severity`	string	`critical`, `warning` nebo `info`
`issue_report.status`	string	`open` nebo `resolved`
`issue_report.source`	string	`user` (odesláno z ovládacího panelu) nebo `system` (vytvořeno hodnocením)

Přehodnocení hovoru znovu vytvoří jeho systémem generovaná hlášení problémů, což znovu odešle událost issue.reported pro znovu vytvořená hlášení. Pokud chcete pouze jedno oznámení pro každý základní problém, deduplikujte podle call_id + title.

Události testovacích hovorů

`test-call.completed`

Odesílá se, když běh testovacího hovoru dosáhne koncového stavu — completed nebo failed, včetně běhů, které selhaly při spuštění a nikdy nevytvořily hovor. Neblokující. Užitečné pro napojení dávkových běhů CI na vaše systémy chatu a oznámení.

{
  "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"
}

Pole	Typ	Popis
`test_call_run.target_type`	string	`agent` nebo `phone_number`
`test_call_run.target_id`	integer	ID agenta nebo telefonního čísla, na které byl běh zaměřen, odpovídající `target_type`
`test_call_run.status`	string	`completed` nebo `failed`
`test_call_run.call_id`	integer \| null	`null`, pokud běh selhal před uskutečněním hovoru
`test_call_run.error_message`	string	Při úspěchu prázdné

Události upozornění

`alert.triggered`

Odesláno, když pravidlo upozornění s povoleným kanálem Doručovat do webhooků vývojářů překročí svou prahovou hodnotu. Neblokující. Pravidlo se aktivuje jednou a poté dodržuje dobu prodlevy, takže trvající překročení vytvoří jednu událost za každé okno doby prodlevy.

{
  "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"
}

Pole	Typ	Popis
`event_id` (v `data`)	UUID	ID aktivace upozornění — odlišné od doručovacího `event_id` obálky
`rule_id`, `rule_name`	UUID, řetězec	Pravidlo, které se aktivovalo
`metric`	řetězec	`success_rate`, `failure_rate`, `avg_score`, `call_volume` nebo `suite_regression`
`comparator`	řetězec	`lt`, `lte`, `gt` nebo `gte`
`metric_value`	číslo	Hodnota metriky v okně, kdy se pravidlo aktivovalo
`threshold`	číslo	Nakonfigurovaná prahová hodnota
`window_hours`	celé číslo	Klouzavé vyhodnocovací okno
`fired_at`	časové razítko

Informace o vytváření pravidel, metrikách, dobách prodlevy a e-mailových / Slack kanálech najdete v průvodci upozorněními.

Související

telephony.incoming / web.incoming

Blokující datová část příchozího hovoru, na kterou musíte odpovědět.

telephony.complete / web.complete

Přepis a metriky po hovoru.

Koncové body webhooků

Přihlaste URL k odběru podmnožiny těchto událostí.

Funkční nástroje

Jak se generují události telephony.tool / web.tool.

Webhooks

Function Tools

Události hovorů

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Hlasové události

`voice.ready`

`voice.failed`

Události kvality

`call.graded`

`issue.reported`

Události testovacích hovorů

`test-call.completed`

Události upozornění

`alert.triggered`

Související

telephony.incoming / web.incoming

telephony.complete / web.complete

Koncové body webhooků

Funkční nástroje

​Události hovorů

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Hlasové události

​voice.ready

​voice.failed

​Události kvality

​call.graded

​issue.reported

​Události testovacích hovorů

​test-call.completed

​Události upozornění

​alert.triggered

​Související

telephony.incoming / web.incoming

telephony.complete / web.complete

Koncové body webhooků

Funkční nástroje

Události hovorů

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Hlasové události

`voice.ready`

`voice.failed`

Události kvality

`call.graded`

`issue.reported`

Události testovacích hovorů

`test-call.completed`

Události upozornění

`alert.triggered`

Související