Webhooks

Tapahtumaluettelo

Kaikki webhook-tapahtumatyypit, jotka ThunderPhone lähettää.

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 — lukuun ottamatta vuorokohtaisia tapahtumia telephony.turn / web.turn, jotka toimitetaan vain päätepisteisiin, joissa ne nimetään erikseen).

Nämä tapahtumat toimitetaan kahdella tavalla:

• Päätepistetoimitukset ovat aina estämättömiä ilmoituksia, joissa käytetään uudelleenyrityksiä: vastaa millä tahansa 2xx-tilakoodilla; kirjekuori sisältää event_id-tunnisteen deduplikointia varten.
• Estävät vaihdot suoritetaan vain vanhassa yhden URL-osoitteen webhookissa: telephony.incoming / web.incoming -määrityspyyntö (webhook-tilan numerot ja widget-avaimet, 10 s:n aikakatkaisu) sekä webhook-tilan työkalukutsu. Vastauksesi muokkaa käynnissä olevaa puhelua.

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

Puhelutapahtumat#

telephony.incoming#

Lähetetään, kun saapuva puhelu saapuu johonkin puhelinnumeroistasi. Päätepistetoimitukset ovat lähetä ja unohda -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 täydellinen pyyntö- ja vastausskeema kohdasta 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#

Lähetetään, kun saapuva tai lähtevä puhelu päättyy. Ei estävä. Sisältää transkription, tallenteen URL-osoitteen, kun se on saatavilla, sekä laskutusyhteenvedon. Katso hyötykuorman skeema kohdasta telephony.complete / web.complete.

telephony.tool#

Lähetetään sen jälkeen, kun puhelu kutsuu toimintotyökalua. Ei estävä tarkastusilmoitus — työkalu on jo suoritettu, kun tämä tapahtuma toimitetaan; se kattaa omat toimintotyö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 suoritetun toiminnon tulos: onnistumisessa {"status": <http status>, "response": <your endpoint's JSON>} tai epäonnistumisessa {"status": <status>, "error": "<message>"}.

telephony.turn#

Lähetetään puhelun ollessa käynnissä, kerran jokaisesta puhetta sisältävästä vuorosta sen tapahtuessa — agentin puhutut vastaukset ja soittajan transkriboidut vuorot. Voit seurata käynnissä olevaa keskustelua tavallisten webhookien kautta kyselyn sijaan GET /v1/calls/{call_id}/transcript. Ei estävä.

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

web.incoming#

telephony.incoming-tapahtuman verkkokanavavastine, joka lähetetään, kun web-widgetin istunto tai rakennustyökalun mikrofonitestipuhelu alkaa. Päätepistetoimitukset ovat lähetä ja unohda -ilmoituksia jokaisesta verkkoistunnosta. Julkaistavat avaimet, joissa on mode="webhook", vastaanottavat lisäksi estävän määrityspyynnön vanhassa webhookissa — kyseisellä estävällä pyynnöllä on eri rakenne (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 literaali "web". Webhook-tilassa olevien widgetistuntojen 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ä.

web.complete#

telephony.complete-tapahtuman verkkokanavavastine, joka kattaa web-widgetin puhelut (direction: "web") ja rakennustyökalun mikrofonitestipuhelut (direction: "test"). Ei estävä. Hyötykuorman rakenne on sama kuin telephony.complete-tapahtumassa, lisänä origin_domain, ja from_number-arvoksi on asetettu "web".

web.tool#

telephony.tool-tapahtuman verkkokanavavastine. data sisältää origin_domain-arvon from_number / to_number-arvojen sijaan.

web.turn#

telephony.turn-tapahtuman verkkokanavavastine, joka kattaa web-widgetin puhelut 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.

Puhetapahtumat#

Mukautetun puheäänen luonti on asynkronista. Näiden estämättömien tapahtumien avulla voit reagoida lopulliseen tulokseen sen sijaan, että kyselisit toistuvasti kloonin tietojen päätepistettä.

voice.ready#

Lähetetään, kun mukautetun puheäänen käsittely valmistuu ja se voidaan määrittää agentille.

{
  "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 puheäänen käsittely päättyy pysyvään virheeseen.

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

Laatua koskevat tapahtumat#

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

issue.reported#

Lähetetään, kun ongelmaraportti luodaan — joko käyttäjän hallintapaneelista tekemänä (source: "user") tai puheluarvioinnin 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"
}

Testipuhelutapahtumat#

test-call.completed#

Lähetetään, kun testipuhelun suoritus saavuttaa lopullisen tilan — completed tai failed, mukaan lukien suoritukset, jotka epäonnistuivat käynnistyksessä eivätkä koskaan muodostaneet puhelua. Ei estä muuta käsittelyä. Hyödyllinen eräajona tehtävien CI-suoritusten 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"
}

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 sen jälkeen jäähtymisaikaansa, joten jatkuva ylitys tuottaa yhden tapahtuman kutakin jäähtymisikkunaa 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"
}

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

Aiheeseen liittyvät#