--- title: "Tapahtumaluettelo" description: "Kaikki webhook-tapahtumatyypit, jotka ThunderPhone lähettää." --- Jokaisella webhookin rungolla on `type`-kenttä, jonka arvo on yksi tämän sivun tapahtumatyypeistä. Kun tilaat [päätepisteen](/fi/webhooks/endpoints), `events`-taulukon on sisällettävä haluamasi tapahtumatyypit (tai sen on oltava tyhjä, jos haluat tilata kaikki — lukuun ottamatta vuorokohtaisia tapahtumia [`telephony.turn`](#telephony-turn) / [`web.turn`](#web-turn), jotka toimitetaan vain päätepisteisiin, joissa ne on nimetty erikseen). Nämä tapahtumat toimitetaan kahdella tavalla: * **Päätepistetoimitukset** ovat aina **estämättömiä** ilmoituksia, joissa käytetään [uudelleenyrityksiä](/fi/webhooks/overview): vastaa millä tahansa 2xx-vastauksella; kuori sisältää `event_id`-kentän duplikoinnin poistamista varten. * **Estävät** vaihdot suoritetaan vain [vanhassa yhden URL-osoitteen webhookissa](/fi/webhooks/overview): [`telephony.incoming` / `web.incoming`](/fi/webhooks/call-incoming) -määrityspyynnössä (webhook-tilan numerot: 13 s, mukaan lukien yksi uudelleenyritys; webhook-tilan widget-avaimet: 10 s) sekä webhook-tilan [työkalun välityksessä](/fi/tools/overview). Vastauksesi muokkaa käynnissä olevaa puhelua. Alla olevat esimerkkikuormat näyttävät päätepistekuoren siirtojärjestyksessä (avaimet aakkosjärjestyksessä: `data`, `event_id`, `type`); vanhat toimitukset sisältävät saman `data`-sisällön ilman `event_id`-kenttää. ## Puhelutapahtumat ### `telephony.incoming` Lähetetään, kun saapuva puhelu tavoittaa jonkin [puhelinnumeroistasi](/api-reference/phone-numbers). Päätepistetoimitukset ovat jokaisesta saapuvasta puhelusta lähetettäviä ei-estäviä ilmoituksia riippumatta siitä, onko numero määritetty agentille vai webhookille. Numerot, joille ei ole määritetty agenttia, vastaanottavat lisäksi **estävässä** määrityspyynnössä vanhaan webhookiin — katso [`telephony.incoming` / `web.incoming`](/fi/webhooks/call-incoming), jossa on koko pyynnön ja vastauksen skeema. ```json { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `telephony.complete` Lähetetään, kun saapuva tai lähtevä puhelu päättyy. Ei-estävä. Sisältää litteroinnin, tallenteen URL-osoitteen, kun se on saatavilla, sekä laskutusyhteenvedon. Katso [`telephony.complete` / `web.complete`](/fi/webhooks/call-complete) hyötykuorman skeemaa varten. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `telephony.tool` Lähetetään sen jälkeen, kun puhelu kutsuu [funktiotyökalua](/fi/tools/overview). Ei-estävä tarkastusilmoitus — työkalu on jo suoritettu, kun tämä tapahtuma toimitetaan; se kattaa omat funktiotyökalusi ja sisäänrakennetun `send_sms`-työkalun (ei muita sisäänrakennettuja, tietämyskanta-, sovellusyhteys- tai MCP-työkaluja). Työkalulle `send_sms` sekä `arguments.to` että `arguments.body` ovat `[REDACTED]`. Myös valmistumislitteroinnit peittävät ne; hae sisältö ja vastaanottaja organisaatiokohtaisesta SMS-resurssista vastauksen `message_id`-arvon avulla. ```json { "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: `{"status": , "response": }` onnistumisessa tai `{"status": , "error": ""}` epäonnistumisessa. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `telephony.turn` Lähetetään puhelun ollessa **käynnissä**, kerran jokaisesta puhetta sisältävästä vuorosta sen tapahtuessa — agentin puhutut vastaukset ja soittajan litteroidut vuorot. Voit seurata reaaliaikaista keskustelua tavallisten webhookien kautta sen sijaan, että kyselisit toistuvasti [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript)-päätepistettä. Ei-estävä. **Nimenomainen tilaus vaaditaan.** Toisin kuin kaikkia muita tapahtumatyyppejä, vuorotapahtumia ei koskaan toimiteta tyhjän `events`-taulukon kautta (tilaa kaikki). Päätepiste vastaanottaa niitä vain, kun sen `events`- luettelo sisältää nimenomaisesti `telephony.turn` / `web.turn`. ```json { "data": { "call_id": 987654321, "entry_type": "completion", "from_number": "+14155550199", "position": 7, "role": "assistant", "start_ms": 15200, "text": "How many employees does your company have?", "to_number": "+15551234567" }, "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e", "type": "telephony.turn" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `position` | integer | Vuoron indeksi puheluhistoriassa — vakaa tunniste järjestämistä varten | | `role` | string | `assistant` (agentin puhe) tai `user` (soittajan puhe) | | `text` | string | Vuoron litterointiteksti sellaisena kuin se tiedetään lähetyshetkellä | | `entry_type` | string | Taustalla olevan historiatietueen tyyppi: `completion` (agentti) tai `user_turn` / `span` (soittaja) | | `start_ms`, `end_ms` | integer | Äänen siirtymät millisekunteina puhelun alusta; mukana vain, kun toistoaikataulu oli jo tiedossa lähetyshetkellä | Toimitus on vähintään kerran -tyyppinen, ja vuorot voivat saapua **väärässä järjestyksessä**: poista kaksoiskappaleet kirjekuoren `event_id`-arvon perusteella ja järjestä `position`-arvon mukaan. Soittajan litteroinnit voivat vielä tarkentua lähetyksen jälkeen; puhelun jälkeinen [`telephony.complete`](/fi/webhooks/call-complete)-litterointi on ensisijainen. Vain puhutut vuorot lähetetään — työkalukutsut, kuiskaukset ja muut sisäiset tietueet eivät koskaan näy tässä virrassa. ### `web.incoming` `telephony.incoming`-tapahtuman verkkokanavavastine, joka lähetetään, kun [verkko-widgetin](/fi/widget/overview) istunto tai rakennustyökalun mikrofonitestipuhelu alkaa. Päätepistetoimitukset ovat ei-estäviä kaikille verkkoistunnoille. Julkaistavat avaimet tilassa `mode="webhook"` vastaanottavat lisäksi **estävässä** määrityspyynnössä vanhaan webhookiin — kyseisellä estävällä pyynnöllä on eri rakenne (`origin_domain`, `publishable_key_prefix`; ei puhelinnumeroita). Katso [`telephony.incoming` / `web.incoming`](/fi/webhooks/call-incoming). ```json { "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 `"web"`. Webhook-tilan widget- istunnoissa `to_number` on tyhjä (istunnon agentin numero määritetään määrityksen jälkeen); rakennustyökalun mikrofonitestipuheluissa `origin_domain` ja `publishable_key_prefix` ovat tyhjiä. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `web.complete` `telephony.complete`-tapahtuman verkkokanavavastine, joka kattaa verkko- widgetpuhelut (`direction: "web"`) ja rakennustyökalun mikrofonitestipuhelut (`direction: "test"`). Ei-estävä. Hyötykuorman rakenne on sama kuin [`telephony.complete`](/fi/webhooks/call-complete)-tapahtumassa, lisäksi mukana on `origin_domain`, ja `from_number` on asetettu arvoon `"web"`. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | Vanhassa yhden URL-osoitteen webhookissa rakennustyökalun mikrofonitestipuhelut raportoidaan historiallisesti muodossa `telephony.complete` — vain `direction: "web"`-puhelut käyttävät siinä tyyppiä `web.complete`. Päätepistejärjestelmä yhdistää sekä verkko- että testipuhelut muotoon `web.*`. Historialliset hyötykuormat voivat sisältää vanhat `direction`-arvot `widget` tai `mic`. ### `web.tool` `telephony.tool`-tapahtuman verkkokanavavastine. `data` sisältää `origin_domain`-arvon `from_number` / `to_number`-arvojen sijaan. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `web.turn` [`telephony.turn`](#telephony-turn)-tapahtuman verkkokanavavastine, joka kattaa verkko-widgetpuhelut ja rakennustyökalun mikrofonitestipuhelut. Hyötykuorman rakenne on sama, mutta siinä käytetään `origin_domain`-arvoa `from_number` / `to_number`-arvojen sijaan. Kuten `telephony.turn`, se edellyttää **nimenomaista tilausta** — sitä ei koskaan toimiteta tyhjän `events`-taulukon kautta. | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun agentti oli määritetty | ### `call.transfer_completed` Lähetetään kerran puhelua kohden [puhelunsiirron](/fi/guides/call-transfers) lopputuloksen yhteydessä: kylmä siirto tai ihmisten välinen silta, joka jää jäljelle lämpimästä siirrosta, kun agentti poistuu puhelusta. Ei estävä, ja toimitetaan vain päätepisteisiin (ei koskaan vanhaan yhden URL-osoitteen webhookiin). Saapuu puhelun `telephony.complete`-tapahtuman jälkeen: kun operaattori ottaa puhelun haltuunsa tai siirto epäonnistuu tai, kun ThunderPhone on sillannut puhelun, kun silta päättyy. ```json { "data": { "agent_id": 12, "agent_name": "Front desk", "bridge_kind": "cold_fallback", "bridge_seconds": 255, "bridge_total_cents": 5, "call_id": 987654321, "destination": "+15555550102", "sip_status": 403, "transfer_outcome": "bridged" }, "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f", "type": "call.transfer_completed" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `call_id` | integer | Siirretty puhelu | | `agent_id` | integer \| null | Puhelun käsitellyt agentti, kun sellainen oli määritetty | | `agent_name` | string \| null | Puhelun käsitellyt agentti, kun sellainen oli määritetty | | `transfer_outcome` | string | `refer_accepted`: operaattori otti puhelun haltuunsa. `bridged`: ThunderPhone piti soittajan ja kohteen itse yhdistettyinä joko siksi, että operaattori kieltäytyi kylmästä siirrosta, tai siksi, että lämpimän siirron agentti poistui puhelusta. `bridge_unanswered`: operaattori kieltäytyi kylmästä siirrosta, eikä kohde vastannut ThunderPhonen omaan puheluun. `failed`: siirto ei onnistunut ja puhelu päättyi | | `destination` | string \| null | Numero, johon puhelu siirrettiin | | `sip_status` | integer \| null | Operaattorin SIP-tila, kun se kieltäytyi kylmästä siirrosta: `403` (esimerkiksi Twilio-runkoyhteys ilman puhelunsiirtoa), `405` tai `501`. `null`, kun operaattori ei kieltäytynyt siitä | | `bridge_kind` | string \| null | Vain `bridged`: `cold_fallback` (kylmä siirto, josta kieltäydyttiin ja jonka ThunderPhone yhdisti) tai `warm` (lämpimän siirron kaksi osapuolta agentin poistuttua) | | `bridge_seconds` | integer \| null | Vain `bridged`: ThunderPhonen laskuttama sillatun puhelun aika sekunteina | | `bridge_total_cents` | integer \| null | Vain `bridged`: sillan hinta Yhdysvaltain sentteinä mahdollisen maksuttoman puheluhyvityksen jälkeen, laskutetaan erikseen puhelun `billing_total_cents`-arvosta | Samat arvot ovat [puheluobjektissa](/api-reference/calls#call-object) nimillä `transfer_outcome`, `transfer_destination`, `transfer_sip_status`, `transfer_bridge_kind`, `transfer_bridge_seconds` ja `transfer_bridge_total_cents`. `event_id` on sama jokaisessa toimituksessa samalle puhelulle, joten toistettu ilmoitus ei koskaan tuota toista tapahtumaa. --- ## SMS-tapahtumat SMS-tapahtumat kuvaavat organisaation yhdistetyn Twilio- tai Telnyx-tilin kautta lähetettyjä viestejä. Viestin sisältö jätetään pois ja `to` peitetään. Hae organisaatiokohtainen viesti osoitteesta [`GET /v1/sms/{message_id}`](/api-reference/sms#retrieve-a-message), kun tarvitset sen sisältöä tai vastaanottajaa. ### `sms.sent` Lähetetään, kun asiakkaan operaattori hyväksyy lähtevän SMS-pyynnön. Tämä ei ole laitteen toimitusvahvistus. ```json { "data": { "accepted_at": "2026-09-19T15:42:10.113Z", "agent_id": 12, "call_id": 987654321, "created_at": "2026-09-19T15:42:09.901Z", "direction": "outbound", "error_code": null, "error_message": null, "from_number": "+15551234567", "id": "313a3117-827b-46e9-a01a-ac1493838724", "provider": "twilio", "provider_id": "SM0123456789abcdef0123456789abcdef", "segment_count": 1, "source": "agent_tool", "status": "accepted", "to": "[REDACTED]" }, "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37", "type": "sms.sent" } ``` ### `sms.failed` Lähetetään pysyvän operaattorihylkäyksen jälkeen, kun tilapäisten virheiden uudelleenyritykset on käytetty loppuun tai kun lopputulos on pysyvästi tuntematon. `error_code` on vakaa ThunderPhone-koodi ja `error_message` kertoo asiakkaan tarvittavan toimenpiteen, kun sellainen on saatavilla. `status: "unknown"` tarkoittaa, että operaattori on voinut hyväksyä SMS-viestin; täsmäytä se operaattorin lokissa, koska ThunderPhone ei lähetä sitä automaattisesti uudelleen. ### `sms.received` Varattu saapuvien SMS-viestien tuelle. Nykyisessä versiossa ei lähetetä `sms.received`-tapahtumia. Saapuvien viestien operaattoriwebhookin määritys ja allekirjoituksen vahvistus julkaistaan erikseen. --- ## Puhetapahtumat Mukautetun äänen luonti on asynkroninen. Näiden estämättömien tapahtumien avulla voit reagoida lopulliseen tulokseen sen sijaan, että kyselisit toistuvasti [kloonin tietojen päätepistettä](/api-reference/custom-voices#list-and-retrieve-clones). `voice.ready` ja `voice.failed` toimitetaan vain koko organisaation kattavaan päätepisteeseen, jossa on `events: []`. Niitä ei voi valita nimenomaisiksi tapahtumasuodattimiksi. ### `voice.ready` Lähetetään, kun mukautetun äänen käsittely valmistuu ja ääni voidaan määrittää agentille. ```json { "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` Lähetetään, kun mukautetun äänen käsittely päättyy pysyvään virheeseen. ```json { "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" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `voice.id` | merkkijono | Mukautetun äänen julkinen tunniste | | `voice.name` | merkkijono | Agentin ääniarvo muodossa `custom:` | | `voice.display_name` | merkkijono | Organisaatiolle näkyvä äänen nimi | | `voice.language` | merkkijono | Kloonin yksittäisen kielen koodi | | `voice.gender` | merkkijono | `male`, `female` tai tyhjä merkkijono | | `voice.status` | merkkijono | `ready` kohteelle `voice.ready`; `failed` kohteelle `voice.failed` | | `voice.failure_reason` | merkkijono | Tyhjä onnistumisessa; käsittelyvirheen tiedot virheessä | | `voice.created_at`, `voice.updated_at` | aikaleima | ISO 8601 -aikaleimat | | `reason` | merkkijono | Virheen tiedot; mukana vain kohteessa `voice.failed` | --- ## Laatutapahtumat ### `call.graded` Lähetetään aina, kun puhelun [tekoälyarviointi](/api-reference/calls#ai-call-grading) valmistuu. Ei-estävä. ```json { "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…" }, "report": null }, "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "type": "call.graded" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun hoitanut agentti, kun agentti oli määritetty | | `agent_name` | string \| null | Puhelun hoitanut agentti, kun agentti oli määritetty | | `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 löytämät ongelmamerkkijonot | | `grade.status` | string | Aina `completed` — vain valmistuneet ajot lähettävät tapahtuman | | `grade.grader_model` | string | Tuloksen tuottanut arviointimalli (esim. `heuristic-v1`) | | `grade.graded_at`, `grade.created_at` | timestamp | | | `report` | object \| null | Asiakkaalle näkyvä [puheluraportti](/api-reference/calls#call-report): lopputuloksen tunniste, huomiota vaativan tilan merkintä ja syy, soittaja, yhden rivin yhteenveto, soittajan kokemus. Varhaisessa heuristisessa arvioinnissa se on `null` tai `pending`-raportti, jonka kentät ovat paikkamerkkejä; täyden arvioinnin tapahtuma sisältää valmiin raportin | Puhelu voidaan arvioida useammin kuin kerran — nopeaa heuristista arviointia seuraa usein täyden mallin arviointi, kun tallenne on saatavilla, ja myös manuaaliset uudelleenarvioinnit ovat mahdollisia. Jokainen valmistunut suoritus lähettää oman `call.graded`-tapahtumansa; käsittele viimeisintä `graded_at`-arvoa ensisijaisena tietona. ### `call.data_extracted` Lähetetään aina, kun strukturoidun datan poiminta valmistuu onnistuneesti, mukaan lukien myöhäinen uudelleenyritys `telephony.complete`- / `web.complete`-tapahtuman jälkeen tai manuaalinen uudelleensuoritus [`POST /v1/calls/{call_id}/extract`](/api-reference/calls#run-data-extraction)-kutsulla. Ei-estävä. Estävässä poimintatilassa valmistumistapahtuma odottaa normaalisti enintään 75 sekunnin poimintäbudjetin ajan. Jos poimintatyöprosessi katoaa, tuotannon viimeistelytyhjennys (viiden minuutin välein) vapauttaa valmistumistapahtuman, jonka `blocking_deadline_at` on umpeutunut, ennen kuin se aloittaa uuden poimintayrityksen. Myöhempi onnistuminen toimitetaan erikseen tällä tapahtumalla. Poimitut arvot ovat mallin tulkinta keskustelusta. Jokainen muu kuin null-arvo sisältää lainauksen, puhujan roolin ja vuoroindeksin, joihin se perustuu, sekä suoritustasoisen varmennusmerkinnän. Vahvista tulos ennen rahaa, identiteettiä tai käyttöoikeuksia koskevia päätöksiä. ```json { "data": { "call_id": 987654321, "agent_id": 12, "agent_name": "Acme intake", "extracted_data": { "status": "completed", "fields": { "customer_name": "Alex Morgan", "appointment_date": "2026-04-23" }, "evidence": { "customer_name": { "quote": "My name is Alex Morgan", "speaker_role": "caller", "turn_index": 4 }, "appointment_date": { "quote": "April 23 works for me", "speaker_role": "caller", "turn_index": 7 } }, "verification": "verified", "field_reasons": {}, "schema_version": "92850758e231a3c95a..." }, "extracted_at": "2026-04-20T18:25:11.002Z", "model": "", "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23." }, "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef", "type": "call.data_extracted" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun hoitanut agentti, jos sellainen oli määritetty | | `agent_name` | string \| null | Puhelun hoitanut agentti, jos sellainen oli määritetty | | `summary` | string \| null | Valmistunut [puheluyhteenveto](/fi/webhooks/call-complete), kun agentilla on **Luo puheluyhteenveto** käytössä, joten myös myöhäinen poimintatapahtuma toimittaa yhteenvedon, joka ei ehtinyt valmistumisikkunaan; muulloin `null`. Agentit, joilla on yhteenveto mutta ei poimintakenttiä, eivät koskaan lähetä tätä tapahtumaa: hae myöhäinen yhteenveto komennolla `GET /v1/calls/{call_id}` | | `extracted_data.status` | string | Tälle tapahtumalle aina `completed` | | `extracted_data.fields` | object | Arvot on avainnettu määritetyillä poimintakenttien avaimilla; arvo `null` tarkoittaa, ettei arvo ole saatavilla | | `extracted_data.evidence` | object | Todisteet on avainnettu poimintakentän mukaan. Muulla kuin null-arvolla on täsmällinen rakenteellisesti tarkistettu lainaus (enintään 1 000 merkkiä), `speaker_role` (`caller` tai `agent`) ja `turn_index`; mallin palauttamat pidemmät lainaukset hylätään katkaisemisen sijaan, ja todiste on `null` aina, kun sen kenttä on `null` | | `extracted_data.verification` | string | `verified` vain, kun riippumaton todistetarkistus palautti täsmälleen yhden kelvollisen päätelmän jokaiselle ehdokaskentälle. `unavailable` tarkoittaa, että tarkistus epäonnistui, aikakatkaistiin, sille ei riittänyt budjettia tai se palautti virheellisen muotoista tai osittaista tulostetta. Kokonaan saatavilla olematon tarkistus säilyttää rakenteellisesti perustellut arvot asiakkaan tarkistettaviksi. Osittaisessa tulosteessa kelvolliset päätelmät otetaan käyttöön ja jokainen ehdokas, jolla ei ole täsmälleen yhtä kelvollista päätelmää, asetetaan null-arvoksi | | `extracted_data.field_reasons` | object | Syyt kentittäin kentille, jotka asetettiin null-arvoksi rakenteellisen perustelun tai riippumattoman varmentajan vuoksi | | `extracted_data.schema_version` | string | Tähän poimintaan käytetyn täsmällisen kenttäskeeman tiiviste | | `extracted_at` | timestamp | ISO 8601 -valmistumisaika | | `model` | string | Poimintaan käytetty malli | ### `campaign.completed` Lähetetään kerran, kun kampanja siirtyy tilasta `running` tilaan `completed`, riippumatta siitä, päättyikö sen aikataulu vai saavuttivatko kaikki kontaktit lopputilat. Suorittajan uudelleenyritykset eivät lähetä uutta tapahtumaa. Tämä organisaatiotason elinkaaritapahtuma toimitetaan vain organisaatiokohtaisiin päätepisteisiin, ei agenttikohtaisiin päätepisteisiin. Ei-estävä. ```json { "data": { "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403", "name": "May win-back", "agent_id": 12, "status": "completed", "started_at": "2026-04-20T17:00:00Z", "completed_at": "2026-04-20T18:25:11Z", "counts": { "contacts_total": 150, "completed": 121, "failed": 11, "no_answer": 18, "remaining": 0 } }, "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135", "type": "campaign.completed" } ``` Neljä lopputulosmäärää ovat erillisiä, ja niiden summa on `contacts_total`: `completed` sisältää onnistuneet kontaktit; `no_answer` sisältää lopputilaan päätyneet epäonnistuneet tai yrityskertansa käyttäneet kontaktit, joiden viimeinen lopputulos oli vastaamattomuus; `failed` sisältää kaikki muut lopputilaan päätyneet epäonnistuneet tai yrityskertansa käyttäneet kontaktit; ja `remaining` sisältää odottavat, ajoitetut tai parhaillaan soitettavat kontaktit. Uudelleenyritystä odottava kontakti on `remaining`, vaikka sen viimeisin yritys olisi päättynyt vastaamattomuuteen. Käynnissä olevat puhelut täsmäytetään ennen vain kerran lähetettävää valmistumisen tilannekuvaa. `started_at` on määritetty kampanjan alkamisaika tai kampanjan luontiaika, jos alkamisaikaa ei määritetty. ### `issue.reported` Lähetetään, kun [ongelmaraportti](/api-reference/issue-reports) luodaan — joko käyttäjän hallintapaneelista tekemänä (`source: "user"`) tai puheluarvioinnin automaattisesti luomana (`source: "system"`). Ei-estävä. ```json { "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 | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun hoitanut agentti, jos sellainen oli määritetty | | `agent_name` | string \| null | Puhelun hoitanut agentti, jos sellainen oli määritetty | | `issue_report.severity` | string | `critical`, `warning` tai `info` | | `issue_report.status` | string | `open` tai `resolved` | | `issue_report.source` | string | `user` (tehty hallintapaneelista) tai `system` (arvioinnin luoma) | Puhelun uudelleenarviointi luo uudelleen sen järjestelmän luomat ongelmaraportit, jolloin `issue.reported` lähetetään uudelleen luoduille raporteille. Poista kaksoiskappaleet yhdistelmällä `call_id` + `title`, jos haluat vain yhden ilmoituksen kutakin taustalla olevaa ongelmaa kohti. ### `issue.escalated` Lähetetään, kun ongelmamalli lähetetään ThunderPhonelle henkilöstön tarkistettavaksi: **Ilmoita ThunderPhonelle** -toiminnon jälkeen tai kun Korjaa tekoälyllä ei voi vahvistaa asiakkaan puolella tehtyä korjausta ja reitittää ongelman automaattisesti. Vain organisaationlaajuiset päätepisteet vastaanottavat tämän tapahtuman. ```json { "data": { "automatic": false, "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19", "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894", "status": "open" }, "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda", "type": "issue.escalated" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `automatic` | boolean | `true` automaattiselle eskaloinnille; `false` manuaaliselle eskaloinnille | | `cluster_id` | UUID | Eskaloitu ongelmamalli | | `escalation_id` | UUID | Eskalointitietue | | `status` | string | `open`, kun tapahtuma lähetetään | Tämä on ilmoitus, ei todistenippu. Käytä `cluster_id`-arvoa yhdistääksesi sen ongelmamalliin. Katso [Ilmoita ThunderPhonelle](/fi/guides/issues). --- ## Testipuhelutapahtumat ### `test-call.completed` Lähetetään, kun [testipuheluajo](/api-reference/test-calls#test-call-run-object) saavuttaa lopullisen tilan — `completed` tai `failed`, mukaan lukien ajot, jotka epäonnistuivat käynnistyksessä eivätkä koskaan tuottaneet puhelua. Ei estä suorittamista. Hyödyllinen eräajettavien CI-ajojen liittämiseen keskustelu- ja ilmoitusjärjestelmiisi. ```json { "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 | |-------|------|-------------| | `agent_id` | integer \| null | Puhelun hoitanut agentti, kun sellainen oli määritetty | | `agent_name` | string \| null | Puhelun hoitanut agentti, kun sellainen oli määritetty | | `test_call_run.target_type` | string | `agent` tai `phone_number` | | `test_call_run.target_id` | integer | Agentin tunnus tai puhelinnumeron tunnus, johon ajo kohdistui, `target_type`-arvon mukaisesti | | `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ö](/fi/guides/alerts), jossa **Toimita kehittäjän webhookeihin** -kanava on käytössä, ylittää kynnysarvonsa. Ei estä suorittamista. Sääntö käynnistyy kerran ja noudattaa sen jälkeen jäähtymisaikaansa, joten jatkuva rajan ylitys tuottaa yhden tapahtuman jokaista jäähtymisikkunaa kohti. ```json { "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` (kohteessa `data`) | UUID | Hälytyksen **käynnistymisen** tunnus — eri kuin kirjekuoren toimituksen `event_id` | | `rule_id`, `rule_name` | UUID, string | Käynnistynyt sääntö | | `metric` | string | `success_rate`, `failure_rate`, `avg_score`, `call_volume` tai `suite_regression` | | `comparator` | string | `lt`, `lte`, `gt` tai `gte` | | `metric_value` | number | Mittarin arvo arviointi-ikkunan aikana, jolloin sääntö käynnistyi | | `threshold` | number | Määritetty kynnysarvo | | `window_hours` | integer | Liukuva arviointi-ikkuna | | `fired_at` | timestamp | | Katso [Hälytykset-oppaasta](/fi/guides/alerts), miten luot sääntöjä, mittareita, jäähtymisaikoja sekä sähköposti- ja Slack-kanavia. --- ## Migraatiotapahtumat ### `migration.call.complete` Lähetetään, kun [`POST /v1/migrations/{id}/calls`](/api-reference/migration-calls)-pyynnöllä tehty puhelu päättyy riippumatta siitä, kummalla alustalla se käytiin. Ei estä muita toimintoja. Se saapuu enintään noin 5 minuuttia puhelun päättymisen jälkeen. `data` sisältää kaikki [`telephony.complete`](/fi/webhooks/call-complete)-tapahtuman kentät sekä `migration`-lohkon. ThunderPhonen soittama puhelu lähettää myös tavalliseen tapaan `telephony.complete`-tapahtuman samalla `call_id`-tunnuksella. Toisen alustan puhelu, joka ei ole päättynyt 2 tunnin jälkeen tai jonka migraatio päättyi tai menetti avaimensa ensin, lähetetään tilalla `status: "unknown"` ilman puhelutallennetta. ```json { "data": { "agent_id": 42, "agent_name": "Front desk", "billable_minutes": null, "billing_total_cents": null, "call_id": null, "direction": "outbound", "duration_seconds": 94, "end_reason": "user_hangup", "end_time": "2026-10-06T17:01:34+00:00", "extracted_data": null, "from_number": "+15551234567", "migration": { "arm": "vendor", "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30", "metadata": { "lead_id": "8812" }, "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34", "vendor": "retell", "vendor_call_id": "call_6a1f0e", "vendor_cost_usd": "0.1240" }, "product": "", "recording_mode": "vendor", "recording_url": "https://…", "start_time": "2026-10-06T17:00:00+00:00", "status": "completed", "summary": "The callee booked a table for two on Thursday.", "thunderphone_retained_call_content": true, "to_number": "+14155552671", "transcripts": [ { "content": "Hi Ada, this is Rosa's calling about your booking.", "role": "agent" }, { "content": "Yes, Thursday works.", "role": "user" } ], "transfer_number": null, "unresolved_variables": [], "variables": { "first_name": "Ada" }, "voice": "" }, "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a", "type": "migration.call.complete" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `migration.id` | UUID | Migraatio | | `migration.routing_id` | UUID | Reititetty puhelu sellaisena kuin se palautettiin, kun soitit sen | | `migration.arm` | string | `ours` (ThunderPhone soitti sen) tai `vendor` (toinen alusta soitti sen) | | `migration.vendor` | string | `retell`, `vapi`, `elevenlabs` tai `bland` | | `migration.vendor_call_id` | string \| null | Toisen alustan puhelutunnus; `null`, kun arvo on `ours` | | `migration.metadata` | object | Puhelua soitettaessa lähettämäsi `metadata` | | `migration.vendor_cost_usd` | string \| null | Toisen alustan ilmoittama puhelun hinta, jos se ilmoitti sen | | `call_id` | integer \| null | ThunderPhone-puhelutunnus; `null`, kun arvo on `vendor` | | `status` | string | Kun arvo on `vendor`: `completed`, kun vastaanottaja puhui, `failed`, kun hän ei puhunut, ja `unknown` kuten yllä. Kun arvo on `ours`: kuten `telephony.complete`-tapahtumassa | `vendor`-puheluissa ThunderPhonella ei ole laskutus- tai poimintatietoja: `billable_minutes`, `billing_total_cents` ja `extracted_data` ovat `null`, `product` ja `voice` ovat tyhjiä, `recording_mode` on `vendor`, ja `recording_url` on toisen alustan linkki, jos se antoi sellaisen. ### `migration.rollback` Lähetetään, kun migraation asteittainen siirto ohjaa kaikki puhelut automaattisesti takaisin toiselle alustalle: 3 puhelua ei muodostanut yhteyttä ThunderPhoneen 15 minuutin sisällä, 2 ThunderPhoneen ohjattua puhelua päättyi ennen kuin agentti vastasi tai ThunderPhonen tehtävän lopputulosaste putosi yli määritetyn rajan toisen alustan vastaavaa astetta alemmaksi. Ei estävä, kerran kutakin palautusta kohden. Tämän jälkeen ThunderPhonen puheluosuus on 0 %, ja migraatio on keskeytetty, kunnes joku jatkaa sitä agentin **Migraatio**-välilehdellä. Tietosisältö ei sisällä puhelinnumeroita, litteraatioita eikä puhelutunnuksia. ```json { "data": { "agent_id": 42, "agent_name": "Front desk", "dropped": 0, "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30", "ours": { "graded": 20, "success_rate": 0.8 }, "ours_failed": 3, "ours_percent": 0, "previous_percent": 25, "reason": "ours_failed_burst", "rolled_back_at": "2026-10-10T12:05:00+00:00", "step": 1, "theirs": { "graded": 20, "success_rate": 0.8 }, "vendor": "retell" }, "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e", "type": "migration.rollback" } ``` | Kenttä | Tyyppi | Kuvaus | |-------|------|-------------| | `migration_id` | UUID | Migraatio | | `vendor` | merkkijono | `retell`, `vapi`, `elevenlabs` tai `bland` | | `reason` | merkkijono | `ours_failed_burst` (3 epäonnistunutta yhteyttä 15 minuutissa), `dropped_calls` (2 puhelua päättyi ennen kuin agentti vastasi, 30 minuutin sisällä) tai `rate_gap` (tehtävän lopputulosasteiden ero vähintään `rollback_min_calls` arvioidussa puhelussa kummallakin puolella) | | `previous_percent` | kokonaisluku | ThunderPhonen puheluosuus ennen palautusta | | `ours_percent` | kokonaisluku | Aina `0` | | `step` | kokonaisluku \| null | Aikatauluvaihe, jossa se oli (alkaen arvosta 0) | | `ours` / `theirs` | objekti \| null | Nykyisen vaiheen arvioidut puhelut ja niiden onnistumisaste; `theirs` voi koskea viimeisiä 30 päivää, kun vaiheessa on liian vähän puheluita. `null`, jos niitä ei ollut | | `ours_failed` | kokonaisluku | Viimeisten 15 minuutin aikana lasketut epäonnistuneet yhteydet | | `dropped` | kokonaisluku | Viimeisten 30 minuutin aikana keskeytyneiksi lasketut puhelut | | `rolled_back_at` | aikaleima | | --- ## Aiheeseen liittyvää Estävä saapuvan puhelun hyötykuorma, johon sinun on vastattava. Puhelun jälkeinen transkriptio ja mittarit. Tilaa URL-osoite osaan näistä tapahtumista. Miten `telephony.tool` / `web.tool` -tapahtumat luodaan.