Tapahtumaluettelo

Jokaisessa webhookin rungossa on type-kenttä, jonka arvo on yksi tämän sivun tapahtumatyypeistä. Kun tilaat päätepisteen, events-taulukon on sisällettävä haluamasi tapahtumatyypit (tai sen on oltava tyhjä, jos haluat tilata kaiken). Nämä tapahtumat toimitetaan kahdella tavalla:

Päätepistetoimitukset ovat aina estämättömiä ilmoituksia, joissa on uudelleenyritykset: vastaa millä tahansa 2xx-koodilla; kirjekuori sisältää event_id-tunnuksen, jonka avulla voit poistaa kaksoiskappaleet.
Estävät vaihdot suoritetaan vain vanhassa yhden URL-osoitteen webhookissa: telephony.incoming / web.incoming -määrityspyynnössä (webhook-tilan numerot ja widget-avaimet, 10 s aikakatkaisu) sekä webhook-tilan työkalun välityksessä. Vastauksesi muokkaa käynnissä olevaa puhelua.

Alla olevat esimerkkikuormat näyttävät päätepisteen kirjekuoren siirtojärjestyksessä (avaimet lajiteltu aakkosjärjestykseen: data, event_id, type); vanhat toimitukset sisältävät saman data-sisällön ilman event_id-tunnusta.

Puhelutapahtumat

`telephony.incoming`

Lähetetään, kun saapuva puhelu saapuu johonkin puhelinnumeroistasi. Päätepisteelle toimitettavat tapahtumat ovat fire-and-forget-ilmoituksia, jotka lähetetään jokaisesta saapuvasta puhelusta riippumatta siitä, onko numero määritetty agentille vai webhookille. Numerot, joille ei ole määritetty agenttia, vastaanottavat lisäksi estävän määrityspyynnön vanhassa webhookissa — katso telephony.incoming / web.incoming, josta löydät koko pyyntö-/vastausskeeman.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

Lähetetään, kun saapuva tai lähtevä puhelu päättyy. Ei estävä. Sisältää koko litteroinnin, tallenteen URL-osoitteen ja laskutusyhteenvedon. Katso telephony.complete / web.complete, josta löydät payload-skeeman.

`telephony.tool`

Lähetetään, kun puhelu kutsuu funktiotyökalua. Ei estävä tarkastusilmoitus — työkalu on jo suoritettu, kun tämä tapahtuma toimitetaan; se kattaa omat funktiotyökalusi (ei sisäänrakennettuja työkaluja, tietopankkityökaluja, sovellusyhteystyökaluja tai MCP-työkaluja).

{
  "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 on suoritettu tulos: onnistuneessa tapauksessa {"status": <http status>, "response": <your endpoint's JSON>} tai epäonnistuneessa tapauksessa {"status": <status>, "error": "<message>"}.

`web.incoming`

telephony.incoming-tapahtuman verkkokanavavastine, joka lähetetään, kun verkkowidgetin istunto tai rakennustyökalun mikrofonitestipuhelu alkaa. Päätepisteelle toimitettavat tapahtumat ovat fire-and-forget-ilmoituksia jokaisesta verkkosessiosta. Julkaistavat avaimet, joissa on mode="webhook", vastaanottavat lisäksi estävän määrityspyynnön vanhassa webhookissa — kyseisen estävän pyynnön rakenne on erilainen (origin_domain, publishable_key_prefix; ei puhelinnumeroita). Katso 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 on aina kirjaimellinen arvo "web". Webhook-tilassa olevissa widgetistunnoissa to_number on tyhjä (istunnon agenttinumero määritetään määrityksen jälkeen); rakennustyökalun mikrofonitestipuheluissa origin_domain ja publishable_key_prefix ovat tyhjiä.

`web.complete`

telephony.complete-tapahtuman verkkokanavavastine, joka kattaa verkkowidgetpuhelut (direction: "web") ja rakennustyökalun mikrofonitestipuhelut (direction: "test"). Ei estävä. Payloadin rakenne on sama kuin telephony.complete -tapahtumassa, mutta mukana on origin_domain, ja from_number-arvoksi asetetaan "web".

Vanhassa yhden URL-osoitteen webhookissa rakennustyökalun mikrofonitestipuhelut raportoidaan historiallisesti muodossa telephony.complete — siellä vain direction: "web" -puhelut käyttävät tyyppiä web.complete. Päätepistejärjestelmä yhdistää sekä verkko- että testipuhelut muotoon web.*. Historialliset payloadit voivat sisältää vanhat direction-arvot widget tai mic.

`web.tool`

telephony.tool-tapahtuman verkkokanavavastine. data sisältää origin_domain-kentän kenttien from_number / to_number sijaan.

Laatutapahtumat

`call.graded`

Lähetetään aina, kun puhelun tekoälyarviointi valmistuu. Ei estä muuta käsittelyä.

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

Kenttä	Tyyppi	Kuvaus
`grade.id`	integer	Arvioinnin tunniste
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` tai `no_conversation`
`grade.summary`	string	Yhden kappaleen yhteenveto
`grade.detected_issues`	array	Arvioijan havaitsemat ongelmamerkkijonot
`grade.status`	string	Aina `completed` — vain valmistuneet ajot lähettävät tapahtuman
`grade.grader_model`	string	Tulosarvion tuottanut arvioija (esim. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Puhelu voidaan arvioida useammin kuin kerran — nopeaa heuristista arviota seuraa usein täyden mallin arvio, kun tallenne on saatavilla, ja manuaaliset uudelleenarvioinnit ovat mahdollisia. Jokainen valmistunut ajo lähettää oman call.graded-tapahtumansa; pidä uusinta graded_at-arvoa ensisijaisena.

`issue.reported`

Lähetetään, kun ongelmaraportti luodaan — joko käyttäjän hallintapaneelissa tekemänä (source: "user") tai puhelun arvioinnin automaattisesti luomana (source: "system"). Ei estä muuta käsittelyä.

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

Kenttä	Tyyppi	Kuvaus
`issue_report.severity`	string	`critical`, `warning` tai `info`
`issue_report.status`	string	`open` tai `resolved`
`issue_report.source`	string	`user` (tehty hallintapaneelissa) tai `system` (arvioinnin luoma)

Puhelun uudelleenarviointi muodostaa sen järjestelmän luomat ongelmaraportit uudelleen, mikä lähettää issue.reported-tapahtuman uudelleen luoduille raporteille. Poista duplikaatit arvojen call_id + title perusteella, jos haluat vain yhden ilmoituksen kutakin taustalla olevaa ongelmaa kohden.

Testipuhelutapahtumat

`test-call.completed`

Lähetetään, kun testipuhelun ajo saavuttaa lopullisen tilan — completed tai failed, mukaan lukien ajot, jotka epäonnistuivat käynnistyksessä eivätkä koskaan tuottaneet puhelua. Ei estä muuta käsittelyä. Hyödyllinen eräajettavien CI-ajojen yhdistämiseen chat- ja ilmoitusjärjestelmiisi.

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

Kenttä	Tyyppi	Kuvaus
`test_call_run.target_type`	string	`agent` tai `phone_number`
`test_call_run.target_id`	integer	Ajossa kohteena olleen agentin tai puhelinnumeron tunniste, joka vastaa arvoa `target_type`
`test_call_run.status`	string	`completed` tai `failed`
`test_call_run.call_id`	integer \| null	`null`, kun ajo epäonnistui ennen puhelun soittamista
`test_call_run.error_message`	string	Tyhjä onnistuneessa ajossa

Hälytystapahtumat

`alert.triggered`

Lähetetään, kun hälytyssääntö, jossa Toimita kehittäjän webhookeihin -kanava on käytössä, ylittää kynnysarvonsa. Ei estävä. Sääntö laukeaa kerran ja noudattaa sitten jäähtymisaikaansa, joten jatkuva rajan ylitys tuottaa yhden tapahtuman kutakin jäähtymisaikaikkunaa kohden.

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

Kenttä	Tyyppi	Kuvaus
`event_id` (kohdassa `data`)	UUID	Hälytyksen laukeamisen tunnus — eri kuin kirjekuoren toimituksen `event_id`
`rule_id`, `rule_name`	UUID, merkkijono	Lauennut sääntö
`metric`	merkkijono	`success_rate`, `failure_rate`, `avg_score`, `call_volume` tai `suite_regression`
`comparator`	merkkijono	`lt`, `lte`, `gt` tai `gte`
`metric_value`	numero	Mittarin arvo ikkunan aikana, jolloin sääntö laukesi
`threshold`	numero	Määritetty kynnysarvo
`window_hours`	kokonaisluku	Liukuva arviointi-ikkuna
`fired_at`	aikaleima

Katso Hälytykset-oppaasta, miten luot sääntöjä, mittareita, jäähtymisaikoja sekä sähköposti- ja Slack-kanavia.

Aiheeseen liittyvää

telephony.incoming / web.incoming

Estävä saapuvan puhelun kuorma, johon sinun on vastattava.

telephony.complete / web.complete

Puhelun jälkeinen transkriptio ja mittarit.

Webhook-päätepisteet

Tilaa URL-osoite näiden tapahtumien alijoukolle.

Funktiotyökalut

Miten telephony.tool / web.tool -tapahtumat luodaan.

Webhooks

Function Tools

Puhelutapahtumat

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Laatutapahtumat

`call.graded`

`issue.reported`

Testipuhelutapahtumat

`test-call.completed`

Hälytystapahtumat

`alert.triggered`

Aiheeseen liittyvää

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-päätepisteet

Funktiotyökalut

​Puhelutapahtumat

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Laatutapahtumat

​call.graded

​issue.reported

​Testipuhelutapahtumat

​test-call.completed

​Hälytystapahtumat

​alert.triggered

​Aiheeseen liittyvää

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-päätepisteet

Funktiotyökalut

Puhelutapahtumat

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Laatutapahtumat

`call.graded`

`issue.reported`

Testipuhelutapahtumat

`test-call.completed`

Hälytystapahtumat

`alert.triggered`

Aiheeseen liittyvää