Katalog dogodkov

Vsako telo webhooka ima polje type, katerega vrednost je ena od vrst dogodkov na tej strani. Ko se naročite na končno točko, mora polje events vsebovati želene vrste dogodkov (ali pa biti prazno, če se želite naročiti na vse).

Te dogodke prenašata dva načina dostave:

• Dostave na končno točko so vedno neblokirajoča obvestila s ponovnimi poskusi: odgovorite s poljubnim odgovorom 2xx; ovojnica vsebuje event_id za odstranjevanje podvojenih dogodkov.
• Blokirne izmenjave se izvajajo samo prek starejšega webhooka z enim URL-jem: zahteva za konfiguracijo telephony.incoming / web.incoming (številke v načinu webhook in ključi gradnika, časovna omejitev 10 s) ter odpošiljanje orodij v načinu webhook. Vaš odgovor oblikuje klic v živo.

Spodnji primeri koristnega tovora prikazujejo ovojnico končne točke v vrstnem redu prenosa (ključi so razvrščeni po abecedi: data, event_id, type); starejše dostave vsebujejo enak data brez event_id.

Dogodki klicev

telephony.incoming

Poslano, ko dohodni klic doseže eno od vaših telefonskih številk. Dostave na končne točke so obvestila brez čakanja na odgovor, poslana za vsak dohodni klic, ne glede na to, ali je številka konfigurirana za agenta ali za webhook. Številke brez dodeljenega agenta dodatno prejmejo blokirajočo zahtevo za konfiguracijo na podedovanem webhooku — za celotno shemo zahteve / odgovora glejte 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

Poslano, ko se dohodni ali odhodni telefonski klic konča. Ne blokira. Vključuje prepis, URL posnetka, kadar je na voljo, in povzetek obračuna. Za shemo koristnega tovora glejte telephony.complete / web.complete.

telephony.tool

Poslano, potem ko telefonski klic prikliče orodje funkcije. Ne blokira in služi kot obvestilo za revizijo — orodje je ob dostavi tega dogodka že izvedeno; zajema vaša lastna orodja funkcij (ne vgrajenih orodij, orodij zbirke znanja, povezav aplikacij ali orodij 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 rezultat izvedbe: {"status": <http status>, "response": <your endpoint's JSON>} ob uspehu oziroma {"status": <status>, "error": "<message>"} ob neuspehu.

web.incoming

Ekvivalent telephony.incoming za spletni kanal, poslan ob začetku seje spletnega gradnika ali preizkusnega klica mikrofona v gradniku. Dostave na končne točke so obvestila brez čakanja na odgovor za vsako spletno sejo. Javni ključi v mode="webhook" dodatno prejmejo blokirajočo zahtevo za konfiguracijo na podedovanem webhooku — ta blokirajoča zahteva ima drugačno strukturo (origin_domain, publishable_key_prefix; brez telefonskih številk). Glejte 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 vedno dobesedna vrednost "web". Pri sejah gradnika v načinu webhook je to_number prazen (številka agenta za sejo je dodeljena po konfiguraciji); pri preizkusnih klicih mikrofona v gradniku sta origin_domain in publishable_key_prefix prazna.

web.complete

Ekvivalent telephony.complete za spletni kanal, ki zajema klice spletnega gradnika (direction: "web") in preizkusne klice mikrofona v gradniku (direction: "test"). Ne blokira. Enaka struktura koristnega tovora kot pri telephony.complete, dodatno z origin_domain, pri čemer je from_number nastavljen na "web".

web.tool

Ekvivalent telephony.tool za spletni kanal. data vsebuje origin_domain namesto from_number / to_number.

Glasovni dogodki

Ustvarjanje glasov po meri je asinhrono. Ti neblokirni dogodki vam omogočajo, da se odzovete na končni rezultat, namesto da preverjate končno točko s podrobnostmi klona.

voice.ready

Poslano, ko glas po meri zaključi obdelavo in ga je mogoče dodeliti agentu.

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

Poslano, ko obdelava glasu po meri doseže trajno napako.

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

Dogodki kakovosti

call.graded

Pošlje se, ko se za klic zaključi ocenjevanje z umetno inteligenco. Ne blokira izvajanja.

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

Pošlje se, ko je ustvarjeno poročilo o težavi — bodisi ga uporabnik odda z nadzorne plošče (source: "user") bodisi ga samodejno ustvari ocenjevanje klica (source: "system"). Ne blokira izvajanja.

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

Dogodki testnih klicev

test-call.completed

Pošlje se, ko zagon testnega klica doseže končno stanje — completed ali failed, vključno z zagoni, ki so spodleteli ob zagonu in niso nikoli ustvarili klica. Ne blokira izvajanja. Uporabno za povezovanje paketnih zagonov CI z vašimi sistemi za klepet in obvestila.

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

Dogodki opozoril

alert.triggered

Pošlje se, ko pravilo opozorila z omogočenim kanalom Pošlji v webhooke za razvijalce preseže svoj prag. Ne blokira. Pravilo se sproži enkrat in nato upošteva obdobje ohlajanja, zato trajna kršitev ustvari en dogodek na obdobje ohlajanja.

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

Za ustvarjanje pravil, metrike, obdobja ohlajanja ter e-poštne kanale in kanale Slack glejte vodnik za opozorila.

Povezano