Katalog događaja

Sve vrste webhook događaja koje ThunderPhone šalje.

Svako tijelo webhooka ima polje type čija je vrijednost jedna od vrsta događaja na ovoj stranici. Kada se pretplatite na krajnju točku, polje events mora sadržavati vrste događaja koje želite (ili biti prazno za pretplatu na sve — osim događaja po potezu telephony.turn / web.turn, koji se isporučuju samo krajnjim točkama koje ih izričito navedu).

Ovi se događaji isporučuju na dva načina:

• Isporuke krajnjoj točki uvijek su neblokirajuće obavijesti s ponovnim pokušajima: odgovorite bilo kojim statusom 2xx; omotnica sadrži event_id za uklanjanje duplikata.
• Blokirajuće razmjene izvode se samo putem naslijeđenog webhooka s jednim URL-om: zahtjev za konfiguraciju telephony.incoming / web.incoming (brojevi u načinu rada webhooka i ključevi widgeta, vremensko ograničenje od 10 s) te otprema alata u načinu rada webhooka alata. Vaš odgovor oblikuje poziv uživo.

Primjeri korisnih tereta u nastavku prikazuju omotnicu krajnje točke redoslijedom na mreži (ključevi su poredani abecedno: data, event_id, type); naslijeđene isporuke sadrže isti data bez event_id.

Događaji poziva#

telephony.incoming#

Šalje se kada dolazni poziv stigne na jedan od Vaših brojeva telefona. Isporuke krajnjoj točki su obavijesti bez čekanja odgovora koje se šalju za svaki dolazni poziv, bez obzira na to je li broj konfiguriran za agenta ili webhook. Brojevi bez dodijeljenog agenta dodatno primaju blokirajući zahtjev za konfiguraciju na naslijeđenom webhooku — za cjelovitu shemu zahtjeva / odgovora pogledajte 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#

Šalje se kada završi dolazni ili odlazni telefonski poziv. Nije blokirajuće. Uključuje transkript, URL snimke kada je dostupan i sažetak naplate. Za shemu sadržaja pogledajte telephony.complete / web.complete.

telephony.tool#

Šalje se nakon što telefonski poziv pozove alat funkcije. Obavijest za neblokirajuću reviziju — alat je već izvršen kada se ovaj događaj isporuči; obuhvaća Vaše vlastite alate funkcija (ne ugrađene alate, alate baze znanja, povezivanja aplikacija ili MCP alate).

{
  "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 izvršavanja: {"status": <http status>, "response": <your endpoint's JSON>} pri uspjehu ili {"status": <status>, "error": "<message>"} pri neuspjehu.

telephony.turn#

Šalje se dok je telefonski poziv u tijeku, jednom za svaki govorni potez čim se dogodi — izgovorene dovršetke agenta i transkribirane poteze pozivatelja. Omogućuje Vam praćenje razgovora uživo putem običnih webhookova umjesto anketiranja GET /v1/calls/{call_id}/transcript. Nije blokirajuće.

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

Ekvivalent telephony.incoming za web-kanal, šalje se kada započne sesija web-widgeta ili testni poziv mikrofona u alatu za izradu. Isporuke krajnjoj točki su obavijesti bez čekanja odgovora za svaku web-sesiju. Objavljivi ključevi u mode="webhook" dodatno primaju blokirajući zahtjev za konfiguraciju na naslijeđenom webhooku — taj blokirajući zahtjev ima drukčiji oblik (origin_domain, publishable_key_prefix; bez brojeva telefona). Pogledajte 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 uvijek je doslovna vrijednost "web". Za sesije widgeta u načinu webhooka to_number je prazan (broj agenta sesije dodjeljuje se nakon konfiguracije); za testne pozive mikrofona u alatu za izradu origin_domain i publishable_key_prefix su prazni.

web.complete#

Ekvivalent telephony.complete za web-kanal, obuhvaća pozive web-widgeta (direction: "web") i testne pozive mikrofona u alatu za izradu (direction: "test"). Nije blokirajuće. Ima isti oblik sadržaja kao telephony.complete, uz origin_domain, pri čemu je from_number postavljen na "web".

web.tool#

Ekvivalent telephony.tool za web-kanal. data sadrži origin_domain umjesto from_number / to_number.

web.turn#

Ekvivalent telephony.turn za web-kanal, obuhvaća pozive web-widgeta i testne pozive mikrofona u alatu za izradu. Ima isti oblik sadržaja, s origin_domain umjesto from_number / to_number. Kao i telephony.turn, zahtijeva izričitu pretplatu — nikada se ne isporučuje putem praznog polja events.

Glasovni događaji#

Izrada prilagođenog glasa odvija se asinkrono. Ovi neblokirajući događaji omogućuju vam da reagirate na konačni rezultat umjesto da provjeravate krajnju točku s pojedinostima klona.

voice.ready i voice.failed isporučuju se samo krajnjoj točki na razini organizacije s events: []. Ne mogu se odabrati kao eksplicitni filtri događaja.

voice.ready#

Šalje se kada prilagođeni glas završi obradu i može se dodijeliti 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#

Šalje se kada obrada prilagođenog glasa dosegne trajnu pogrešku.

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

Događaji kvalitete#

call.graded#

Šalje se svaki put kada se za poziv dovrši pokretanje AI ocjenjivanja. Ne blokira izvršavanje.

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

call.data_extracted#

Šalje se svaki put kada se uspješno dovrši ekstrakcija strukturiranih podataka, uključujući naknadni ponovni pokušaj nakon telephony.complete / web.complete ili ručno ponovno pokretanje putem POST /v1/calls/{call_id}/extract. Ne blokira izvršavanje.

U načinu blokirajuće ekstrakcije događaj dovršetka obično čeka najviše 75 sekundi predviđenih za ekstrakciju. Ako se proces radnika za ekstrakciju izgubi, produkcijsko pražnjenje završne obrade (svakih pet minuta) oslobađa dovršetak čiji je blocking_deadline_at istekao prije nego što započne drugi pokušaj ekstrakcije. Naknadni uspjeh isporučuje se zasebno ovim događajem.

{
  "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": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Šalje se jednom kada kampanja prijeđe iz running u completed, bez obzira na to je li njezin raspored završio ili su svi kontakti dosegli završna stanja. Ponovni pokušaji pokretača ne emitiraju drugi događaj. Ovaj događaj životnog ciklusa na razini organizacije isporučuje se samo krajnjim točkama na razini organizacije, a ne krajnjim točkama na razini agenta. Ne blokira izvršavanje.

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

Četiri broja ishoda međusobno se isključuju i zbrojem daju contacts_total: completed sadrži uspješne kontakte; no_answer sadrži završne neuspjele/iscrpljene kontakte čiji je konačni ishod bio neodgovaranje; failed sadrži sve ostale završne neuspjele/iscrpljene kontakte; a remaining sadrži kontakte na čekanju, zakazane kontakte ili kontakte koji se trenutačno pozivaju. Kontakt koji čeka ponovni pokušaj je remaining, čak i kada je njegov najnoviji pokušaj završio bez odgovora. Pozivi u tijeku usklađuju se prije jednokratne snimke dovršetka. started_at je konfigurirani početak kampanje ili vrijeme stvaranja kampanje ako početak nije bio konfiguriran.

issue.reported#

Šalje se kada se izradi prijava problema — bilo da ju korisnik podnese iz nadzorne ploče (source: "user") ili ju ocjenjivanje poziva izradi automatski (source: "system"). Ne blokira izvršavanje.

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

issue.escalated#

Šalje se kada se obrazac problema pošalje ThunderPhoneu na pregled osoblja: nakon Prijavite ThunderPhoneu ili kada Fix with AI ne može potvrditi ispravak na strani korisnika te automatski usmjeri problem. Ovaj događaj primaju samo krajnje točke na razini organizacije.

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

Ovo je obavijest, a ne paket dokaza. Upotrijebite cluster_id za povezivanje s obrascem problema. Pogledajte Prijavite ThunderPhoneu.

Događaji testnih poziva#

test-call.completed#

Šalje se kada pokretanje testnog poziva dosegne završni status — completed ili failed, uključujući pokretanja koja nisu uspjela pri pokretanju i nikada nisu ostvarila poziv. Ne blokira. Korisno za povezivanje skupnih CI pokretanja sa sustavima za chat i obavijesti.

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

Događaji upozorenja#

alert.triggered#

Šalje se kada pravilo upozorenja s uključenim kanalom Dostavi razvojnim webhookovima prijeđe svoj prag. Ne blokira. Pravilo se aktivira jednom, a zatim poštuje svoje razdoblje hlađenja, pa trajno prekoračenje stvara jedan događaj po prozoru hlađenja.

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

Pogledajte vodič za upozorenja za izradu pravila, metrike, razdoblja hlađenja i kanale e-pošte / Slacka.

Povezano#