Katalog událostí

Každé tělo webhooku má 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 endpointu, 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í endpointu jsou vždy neblokující oznámení s opakováním pokusů: 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: v požadavku na konfiguraci telephony.incoming / web.incoming (čísla v režimu webhooku a klíče widgetů, časový limit 10 s) a v režimu webhooku při dispečinku nástrojů. Vaše odpověď ovlivňuje probíhající hovor.

Níže uvedené příklady datových částí ukazují obálku endpointu v pořadí, v jakém se přenáší (klíče jsou ř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 bez ohledu na to, zda je číslo nakonfigurováno pro agenta nebo pro webhook. Čísla bez přiřazeného agenta navíc obdrží blokující požadavek na konfiguraci na starším webhooku — úplné schéma požadavku a odpovědi naleznete v části 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. Nejde o blokující událost. Obsahuje úplný přepis, URL nahrávky a souhrn účtování. Schéma datové části naleznete v telephony.complete / web.complete.

`telephony.tool`

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

`web.incoming`

Ekvivalent telephony.incoming pro webový kanál, odesílaný při zahájení relace webového widgetu nebo testovacího hovoru mikrofonu v editoru. Doručení na endpoint jsou oznámení typu fire-and-forget pro každou webovou relaci. Publikovatelné klíče v režimu mode="webhook" navíc obdrží blokující požadavek na konfiguraci na 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 je vždy doslovná hodnota "web". Pro relace widgetu v režimu webhook je to_number prázdné (číslo agenta relace se přiřadí 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, který zahrnuje hovory webového widgetu (direction: "web") a testovací hovory mikrofonu v editoru (direction: "test"). Nejde o blokující událost. Má stejnou strukturu datové části jako telephony.complete, navíc obsahuje origin_domain a from_number je nastaveno na "web".

Na starším webhooku s jednou URL se testovací hovory mikrofonu v editoru historicky vykazují 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 místo from_number / to_number.

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	Shrnutí v jednom odstavci
`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 možné je i ruční přehodnocení. Každý dokončený běh odesílá 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 dashboardu (source: "user"), nebo jej automaticky vytvoří hodnocení 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 dashboardu) 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 konečné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 propojení dávkových běhů CI s vašimi 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`

Odesílá se, když pravidlo upozornění s povoleným kanálem Doručovat do webhooků vývojářů překročí svůj práh. Neblokující. Pravidlo se spustí jednou a poté dodržuje dobu ochlazení, takže setrvalé porušení podmínky vytvoří jednu událost za každé okno ochlazení.

{
  "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 spuštění upozornění — odlišné od doručovacího `event_id` obálky
`rule_id`, `rule_name`	UUID, řetězec	Pravidlo, které se spustilo
`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 daném okně při spuštění pravidla
`threshold`	číslo	Nastavený práh
`window_hours`	celé číslo	Klouzavé vyhodnocovací okno
`fired_at`	časové razítko

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

Související

telephony.incoming / web.incoming

Blokující datová struktura 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`

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

​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`

Události kvality

`call.graded`

`issue.reported`

Události testovacích hovorů

`test-call.completed`

Události upozornění

`alert.triggered`

Související