Katalog zdarzeń

Każda treść webhooka ma pole type, którego wartość jest jednym z typów zdarzeń na tej stronie. Gdy subskrybujesz endpoint, tablica events musi zawierać typy zdarzeń, które chcesz otrzymywać (lub być pusta, aby subskrybować wszystkie). Te zdarzenia są dostarczane w dwóch stylach:

Dostarczenia do endpointu są zawsze nieblokującymi powiadomieniami z ponownymi próbami: odpowiedz dowolnym kodem 2xx; koperta zawiera event_id do deduplikacji.
Blokujące wymiany są wykonywane tylko w starszym webhooku z pojedynczym URL-em: żądanie konfiguracji telephony.incoming / web.incoming (numery w trybie webhooka i klucze widżetów, limit czasu 10 s) oraz dyspozycja narzędzia w trybie webhooka. Twoja odpowiedź kształtuje trwającą rozmowę.

Przykładowe ładunki poniżej pokazują kopertę endpointu w kolejności przesyłanej przez sieć (klucze posortowane alfabetycznie: data, event_id, type); starsze dostarczenia zawierają te same data bez event_id.

Zdarzenia połączeń

`telephony.incoming`

Wysyłane, gdy połączenie przychodzące dociera na jeden z Twoich numerów telefonów. Dostawy do endpointu to powiadomienia typu „wyślij i zapomnij” wysyłane dla każdego połączenia przychodzącego, niezależnie od tego, czy numer jest skonfigurowany dla agenta, czy dla webhooka. Numery bez przypisanego agenta dodatkowo otrzymują blokujące żądanie konfiguracji w starszym webhooku — pełny schemat żądania / odpowiedzi znajdziesz w 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`

Wysyłane po zakończeniu przychodzącego lub wychodzącego połączenia telefonicznego. Nieblokujące. Obejmuje pełną transkrypcję, adres URL nagrania i podsumowanie rozliczenia. Schemat ładunku znajdziesz w telephony.complete / web.complete.

`telephony.tool`

Wysyłane po wywołaniu przez połączenie telefoniczne narzędzia funkcji. Nieblokujące powiadomienie audytowe — narzędzie zostało już wykonane w momencie dostarczenia tego zdarzenia; dotyczy Twoich własnych narzędzi funkcji (nie wbudowanych narzędzi, bazy wiedzy, połączeń aplikacji ani narzędzi 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 to wynik wykonania: {"status": <http status>, "response": <your endpoint's JSON>} w przypadku powodzenia albo {"status": <status>, "error": "<message>"} w przypadku błędu.

`web.incoming`

Odpowiednik telephony.incoming dla kanału internetowego, wysyłany po rozpoczęciu sesji widżetu internetowego lub testowego połączenia mikrofonowego w kreatorze. Dostawy do endpointu są typu „wyślij i zapomnij” dla każdej sesji internetowej. Klucze publiczne w mode="webhook" dodatkowo otrzymują blokujące żądanie konfiguracji w starszym webhooku — to blokujące żądanie ma inną strukturę (origin_domain, publishable_key_prefix; bez numerów telefonów). Zobacz 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 zawsze ma dosłowną wartość "web". W przypadku sesji widżetu w trybie webhook to_number jest puste (numer agenta sesji jest przypisywany po konfiguracji); w przypadku testowych połączeń mikrofonowych w kreatorze origin_domain i publishable_key_prefix są puste.

`web.complete`

Odpowiednik telephony.complete dla kanału internetowego, obejmujący połączenia widżetu internetowego (direction: "web") oraz testowe połączenia mikrofonowe w kreatorze (direction: "test"). Nieblokujące. Ma taką samą strukturę ładunku jak telephony.complete, plus origin_domain, przy czym from_number ma wartość "web".

W starszym webhooku z jednym adresem URL testowe połączenia mikrofonowe w kreatorze historycznie są raportowane jako telephony.complete — tylko direction: "web" calls use the web.complete type there. System endpointów mapuje zarówno połączenia internetowe, jak i testowe na web.*. Historyczne ładunki mogą zawierać starsze wartości direction: widget lub mic.

`web.tool`

Odpowiednik telephony.tool dla kanału internetowego. data zawiera origin_domain zamiast from_number / to_number.

Zdarzenia jakości

`call.graded`

Wysyłane po zakończeniu uruchomienia oceniania AI dla połączenia. Nieblokują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"
}

Pole	Typ	Opis
`grade.id`	integer	Id oceny
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` lub `no_conversation`
`grade.summary`	string	Jednoakapitowe podsumowanie
`grade.detected_issues`	array	Łańcuchy opisujące problemy wykryte przez oceniający system
`grade.status`	string	Zawsze `completed` — emitowane są tylko zakończone uruchomienia
`grade.grader_model`	string	Oceniający system, który wygenerował wynik (np. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Połączenie może zostać ocenione więcej niż raz — po szybkiej ocenie heurystycznej często następuje pełna ocena modelu, gdy nagranie jest dostępne, możliwe są też ręczne ponowne oceny. Każde zakończone uruchomienie emituje własne zdarzenie call.graded; jako rozstrzygający traktuj najnowszy parametr graded_at.

`issue.reported`

Wysyłane po utworzeniu zgłoszenia problemu — zgłoszonego przez użytkownika z panelu (source: "user") lub automatycznie przez ocenianie połączenia (source: "system"). Nieblokują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"
}

Pole	Typ	Opis
`issue_report.severity`	string	`critical`, `warning` lub `info`
`issue_report.status`	string	`open` lub `resolved`
`issue_report.source`	string	`user` (zgłoszone z panelu) lub `system` (utworzone przez ocenianie)

Ponowne ocenienie połączenia odtwarza zgłoszenia problemów wygenerowane przez system, co ponownie emituje issue.reported dla odtworzonych zgłoszeń. Deduplikuj według call_id + title, jeśli chcesz otrzymywać tylko jedno powiadomienie na każdy bazowy problem.

Zdarzenia połączeń testowych

`test-call.completed`

Wysyłane, gdy uruchomienie połączenia testowego osiągnie status końcowy — completed lub failed, w tym uruchomienia, które nie powiodły się podczas uruchamiania i nigdy nie utworzyły połączenia. Nieblokujące. Przydatne do podłączania wsadowych uruchomień CI do systemów czatu/powiadomień.

{
  "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	Opis
`test_call_run.target_type`	string	`agent` lub `phone_number`
`test_call_run.target_id`	integer	Id agenta lub numeru telefonu, do którego było skierowane uruchomienie, zgodne z `target_type`
`test_call_run.status`	string	`completed` lub `failed`
`test_call_run.call_id`	integer \| null	`null`, gdy uruchomienie nie powiodło się przed wykonaniem połączenia
`test_call_run.error_message`	string	Puste w przypadku powodzenia

Zdarzenia alertów

`alert.triggered`

Wysyłane, gdy reguła alertu z włączonym kanałem Dostarczaj do webhooków deweloperskich przekroczy swój próg. Nieblokujące. Reguła jest wyzwalana raz, a następnie przestrzega okresu wyciszenia, więc utrzymujące się naruszenie generuje jedno zdarzenie na każde okno wyciszenia.

{
  "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	Opis
`event_id` (w `data`)	UUID	Identyfikator wyzwolenia alertu — inny niż `event_id` dostarczenia w obwiedni
`rule_id`, `rule_name`	UUID, string	Reguła, która została wyzwolona
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume` lub `suite_regression`
`comparator`	string	`lt`, `lte`, `gt` lub `gte`
`metric_value`	number	Wartość metryki w oknie, gdy reguła została wyzwolona
`threshold`	number	Skonfigurowany próg
`window_hours`	integer	Kroczące okno oceny
`fired_at`	timestamp

Więcej informacji o tworzeniu reguł, metrykach, okresach wyciszenia oraz kanałach e-mail / Slack znajdziesz w przewodniku po alertach.

Powiązane

telephony.incoming / web.incoming

Blokujący ładunek przychodzącego połączenia, na który musisz odpowiedzieć.

telephony.complete / web.complete

Transkrypcja i metryki po połączeniu.

Punkty końcowe webhooków

Skonfiguruj adres URL do odbierania podzbioru tych zdarzeń.

Narzędzia funkcji

Jak są generowane zdarzenia telephony.tool / web.tool.

Webhooks

Function Tools

Zdarzenia połączeń

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Zdarzenia jakości

`call.graded`

`issue.reported`

Zdarzenia połączeń testowych

`test-call.completed`

Zdarzenia alertów

`alert.triggered`

Powiązane

telephony.incoming / web.incoming

telephony.complete / web.complete

Punkty końcowe webhooków

Narzędzia funkcji

​Zdarzenia połączeń

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Zdarzenia jakości

​call.graded

​issue.reported

​Zdarzenia połączeń testowych

​test-call.completed

​Zdarzenia alertów

​alert.triggered

​Powiązane

telephony.incoming / web.incoming

telephony.complete / web.complete

Punkty końcowe webhooków

Narzędzia funkcji

Zdarzenia połączeń

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Zdarzenia jakości

`call.graded`

`issue.reported`

Zdarzenia połączeń testowych

`test-call.completed`

Zdarzenia alertów

`alert.triggered`

Powiązane