Webhooks

Notikumu katalogs

Visi tīmekļa aizķeres notikumu veidi, ko ThunderPhone izsūta.

Katram tīmekļa aizķeres pamattekstam ir lauks type, kura vērtība ir viens no šajā lapā norādītajiem notikumu tipiem. Abonējot galapunktu, masīvā events jāietver vēlamie notikumu tipi (vai tas jāatstāj tukšs, lai abonētu visus — izņemot notikumus katrā sarunas gājienā telephony.turn / web.turn, kas tiek piegādāti tikai tiem galapunktiem, kuros tie ir skaidri norādīti).

Šie notikumi tiek nodrošināti divos piegādes veidos:

• Galapunktu piegādes vienmēr ir nebloķējoši paziņojumi ar atkārtotiem mēģinājumiem: atbildiet ar jebkuru 2xx; aploksnē ir event_id, ko izmantot dublikātu novēršanai.
• Bloķējoša apmaiņa notiek tikai mantotajā vienas URL tīmekļa aizķerē: telephony.incoming / web.incoming konfigurācijas pieprasījums (tīmekļa aizķeres režīma numuri un logrīku atslēgas, 10 s taimauts) un tīmekļa aizķeres režīma rīku nosūtīšana. Jūsu atbilde nosaka aktīvā zvana gaitu.

Tālāk sniegtajos piemēra datos galapunkta aploksne ir parādīta tās pārsūtīšanas secībā (atslēgas sakārtotas alfabētiski: data, event_id, type); mantotajās piegādēs ir tie paši data bez event_id.

Zvanu notikumi#

telephony.incoming#

Tiek nosūtīts, kad ienākošais zvans sasniedz kādu no jūsu tālruņa numuriem. Galapunkta piegādes ir paziņojumi bez gaidīšanas, kas tiek nosūtīti par katru ienākošo zvanu neatkarīgi no tā, vai numurs ir konfigurēts aģentam vai tīmekļa aizķerei. Numuri bez piešķirta aģenta papildus saņem bloķējošu konfigurācijas pieprasījumu mantotajā tīmekļa aizķerē — pilnu pieprasījuma / atbildes shēmu skatiet sadaļā 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#

Tiek nosūtīts, kad beidzas ienākošs vai izejošs telefonijas zvans. Nebloķējošs. Ietver transkriptu, ieraksta URL, kad tas ir pieejams, un norēķinu kopsavilkumu. Skatiet telephony.complete / web.complete, lai apskatītu slodzes shēmu.

telephony.tool#

Tiek nosūtīts pēc tam, kad telefonijas zvans izsauc funkcijas rīku. Nebloķējošs audita paziņojums — rīks jau ir izpildīts, kad šis notikums tiek piegādāts; tas attiecas uz jūsu pašu funkciju rīkiem (nevis iebūvētiem, zināšanu bāzes, lietotņu savienojumu vai MCP rīkiem).

{
  "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 ir izpildes rezultāts: veiksmīgas izpildes gadījumā {"status": <http status>, "response": <your endpoint's JSON>}, bet kļūmes gadījumā {"status": <status>, "error": "<message>"}.

telephony.turn#

Tiek nosūtīts, kamēr telefonijas zvans notiek, vienu reizi katrai runu saturošai replikai tās rašanās brīdī — aģenta izrunātajām atbildēm un zvanītāja transkribētajām replikām. Ļauj sekot tiešajai sarunai, izmantojot parastas tīmekļa aizķeres, nevis aptaujājot GET /v1/calls/{call_id}/transcript. Nebloķējošs.

{
  "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 ekvivalents tīmekļa kanālā, kas tiek nosūtīts, kad sākas tīmekļa logrīka sesija vai veidotāja mikrofona pārbaudes zvans. Galapunkta piegādes ir paziņojumi bez gaidīšanas par katru tīmekļa sesiju. Publicējamās atslēgas režīmā mode="webhook" papildus saņem bloķējošu konfigurācijas pieprasījumu mantotajā tīmekļa aizķerē — šim bloķējošajam pieprasījumam ir cita struktūra (origin_domain, publishable_key_prefix; nav tālruņa numuru). Skatiet 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 vienmēr ir literālā vērtība "web". Logrīku sesijām tīmekļa aizķeres režīmā to_number ir tukšs (sesijas aģenta numurs tiek piešķirts pēc konfigurācijas); veidotāja mikrofona pārbaudes zvaniem origin_domain un publishable_key_prefix ir tukši.

web.complete#

telephony.complete ekvivalents tīmekļa kanālā, kas aptver tīmekļa logrīka zvanus (direction: "web") un veidotāja mikrofona pārbaudes zvanus (direction: "test"). Nebloķējošs. Tāda pati slodzes struktūra kā telephony.complete, papildus origin_domain, ar from_number, kas iestatīts uz "web".

web.tool#

telephony.tool ekvivalents tīmekļa kanālā. data satur origin_domain, nevis from_number / to_number.

web.turn#

telephony.turn ekvivalents tīmekļa kanālā, kas aptver tīmekļa logrīka zvanus un veidotāja mikrofona pārbaudes zvanus. Tāda pati slodzes struktūra, ar origin_domain, nevis from_number / to_number. Tāpat kā telephony.turn, tam ir nepieciešams skaidri norādīts abonements — tas nekad netiek piegādāts, izmantojot tukšu events masīvu.

Balss notikumi#

Pielāgotas balss izveide ir asinhrona. Šie nebloķējošie notikumi ļauj jums reaģēt uz galarezultātu, nevis veikt periodisku vaicāšanu klona detalizētās informācijas galapunktam.

voice.ready#

Nosūtīts, kad pielāgotas balss apstrāde ir pabeigta un to var piešķirt balss aģentam.

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

Nosūtīts, kad pielāgotas balss apstrāde beidzas ar neatgriezenisku kļūdu.

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

Kvalitātes notikumi#

call.graded#

Nosūtīts, kad zvanam tiek pabeigta MI vērtēšanas izpilde. Nebloķējošs.

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

Nosūtīts, kad tiek izveidots problēmas ziņojums — to vai nu no informācijas paneļa iesniedz lietotājs (source: "user"), vai to automātiski izveido zvanu vērtēšana (source: "system"). Nebloķējošs.

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

Testa zvanu notikumi#

test-call.completed#

Nosūtīts, kad testa zvana izpilde sasniedz galīgo statusu — completed vai failed, tostarp izpildēm, kas neizdevās palaišanas laikā un nekad neveica zvanu. Nebloķējošs. Noderīgi, lai pakešu CI izpildes savienotu ar tērzēšanas un paziņojumu sistēmām.

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

Brīdinājumu notikumi#

alert.triggered#

Nosūtīts, kad brīdinājuma kārtula ar iespējotu kanālu Piegādāt uz izstrādātāju tīmekļa aizķerēm pārsniedz savu slieksni. Nebloķējošs. Kārtula tiek aktivizēta vienreiz un pēc tam ievēro savu atdzišanas periodu, tāpēc ilgstoša pārsniegšana rada vienu notikumu katrā atdzišanas perioda logā.

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

Skatiet brīdinājumu ceļvedi, lai izveidotu kārtulas, konfigurētu metriku, atdzišanas periodus un e-pasta / Slack kanālus.

Saistītie resursi#