Įvykių katalogas

Visi žiniatinklio kabliuko įvykių tipai, kuriuos siunčia ThunderPhone.

Kiekviename žiniatinklio kabliuko turinyje yra type laukas, kurio reikšmė yra vienas iš šiame puslapyje nurodytų įvykių tipų. Kai užsiprenumeruojate galinį tašką, events masyve turi būti norimi įvykių tipai (arba jis turi būti tuščias, jei norite prenumeruoti visus įvykius — išskyrus kiekvieno pokalbio eigos įvykius telephony.turn / web.turn, kurie pristatomi tik į galinius taškus, kuriuose jie aiškiai nurodyti).

Šie įvykiai pristatomi dviem būdais:

• Pristatymai į galinį tašką visada yra neblokuojantys pranešimai su pakartotiniais bandymais: atsakykite bet kuriuo 2xx kodu; voke yra event_id, skirtas dubliavimui šalinti.
• Blokuojantys apsikeitimai vykdomi tik naudojant senstelėjusį vieno URL žiniatinklio kabliuką: tai telephony.incoming / web.incoming konfigūracijos užklausa (žiniatinklio kabliuko režimo numeriai ir valdiklio raktai, 10 s delsa) ir žiniatinklio kabliuko režimo įrankio iškvietimas. Jūsų atsakymas formuoja tiesioginį skambutį.

Toliau pateikti pavyzdiniai duomenų paketai rodo galinio taško voką jo perdavimo tvarka (raktai surikiuoti abėcėlės tvarka: data, event_id, type); senstelėję pristatymai perduoda tuos pačius data be event_id.

Skambučių įvykiai#

telephony.incoming#

Siunčiamas, kai įeinantis skambutis pasiekia vieną iš jūsų telefono numerių. Pristatymas į galinius taškus yra pranešimai, siunčiami nesitikint atsakymo, apie kiekvieną įeinantį skambutį, neatsižvelgiant į tai, ar numeriui sukonfigūruotas agentas, ar žiniatinklio kabliukas. Numeriai be priskirto agento taip pat gauna blokuojančią konfigūracijos užklausą į senąjį žiniatinklio kabliuką — visą užklausos ir atsakymo schemą žr. 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#

Siunčiamas, kai baigiasi įeinantis arba išeinantis telefoninis skambutis. Neblokuojantis. Apima transkripciją, įrašo URL, kai jis pasiekiamas, ir atsiskaitymo suvestinę. Naudingosios apkrovos schemą žr. telephony.complete / web.complete.

telephony.tool#

Siunčiamas, kai telefoninio skambučio metu iškviečiamas funkcijos įrankis. Neblokuojantis audito pranešimas — įrankis jau įvykdytas, kai pristatomas šis įvykis; jis apima jūsų funkcijų įrankius (ne integruotus, žinių bazės, programų ryšio ar MCP įrankius).

{
  "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 yra įvykdymo rezultatas: sėkmės atveju {"status": <http status>, "response": <your endpoint's JSON>}, o nesėkmės atveju — {"status": <status>, "error": "<message>"}.

telephony.turn#

Siunčiamas vykstant telefoniniam skambučiui realiuoju laiku, po vieną kiekvienai kalbą turinčiai replikai — agento ištartiems atsakymams ir skambintojo transkribuotoms replikoms. Leidžia stebėti tiesioginį pokalbį naudojant paprastus žiniatinklio kabliukus, užuot periodiškai užklausus GET /v1/calls/{call_id}/transcript. Neblokuojantis.

{
  "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 atitikmuo žiniatinklio kanale, siunčiamas, kai pradedama žiniatinklio valdiklio sesija arba kūrimo priemonės mikrofono bandomasis skambutis. Pristatymas į galinius taškus yra pranešimai, siunčiami nesitikint atsakymo, apie kiekvieną žiniatinklio sesiją. Publikuojami raktai su mode="webhook" taip pat gauna blokuojančią konfigūracijos užklausą į senąjį žiniatinklio kabliuką — ši blokuojanti užklausa yra kitokios struktūros (origin_domain, publishable_key_prefix; be telefono numerių). Žr. 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 visada yra pažodinė reikšmė "web". Valdiklio seansų žiniatinklio kabliuko režimu to_number yra tuščias (seanso agento numeris priskiriamas po konfigūravimo); kūrimo priemonės mikrofono bandomiesiems skambučiams origin_domain ir publishable_key_prefix yra tušti.

web.complete#

telephony.complete atitikmuo žiniatinklio kanale, apimantis žiniatinklio valdiklio skambučius (direction: "web") ir kūrimo priemonės mikrofono bandomuosius skambučius (direction: "test"). Neblokuojantis. Tokia pati naudingosios apkrovos struktūra kaip telephony.complete, papildomai su origin_domain, o from_number nustatytas į "web".

web.tool#

telephony.tool atitikmuo žiniatinklio kanale. data pateikia origin_domain vietoje from_number / to_number.

web.turn#

telephony.turn atitikmuo žiniatinklio kanale, apimantis žiniatinklio valdiklio skambučius ir kūrimo priemonės mikrofono bandomuosius skambučius. Tokia pati naudingosios apkrovos struktūra, su origin_domain vietoje from_number / to_number. Kaip ir telephony.turn, jam būtina aiški prenumerata — jis niekada nepristatomas naudojant tuščią events masyvą.

Balso įvykiai#

Pasirinktinio balso kūrimas yra asinchroninis. Šie neblokuojantys įvykiai leidžia reaguoti į galutinį rezultatą, užuot apklausus klono išsamios informacijos galinį tašką.

voice.ready ir voice.failed pateikiami tik į visos organizacijos galinį tašką su events: []. Jų negalima pasirinkti kaip aiškių įvykių filtrų.

voice.ready#

Siunčiamas, kai pasirinktinio balso apdorojimas baigiamas ir jį galima priskirti agentui.

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

Siunčiamas, kai pasirinktinio balso apdorojimas patiria negrįžtamą klaidą.

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

Kokybės įvykiai#

call.graded#

Siunčiamas kiekvieną kartą, kai skambučiui užbaigiamas AI vertinimo vykdymas. Neribojantis.

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

Siunčiamas kiekvieną kartą, kai sėkmingai užbaigiamas struktūrizuotų duomenų išgavimas, įskaitant vėlyvą pakartotinį bandymą po telephony.complete / web.complete arba pakartotinį vykdymą rankiniu būdu per POST /v1/calls/{call_id}/extract. Neribojantis.

Blokuojančio išgavimo režimu užbaigimo įvykis paprastai laukia ne ilgiau nei 75 sekundžių išgavimo biudžeto. Jei išgavimo darbuotojo procesas prarandamas, gamybinis užbaigimo išvalymas, vykdomas kas penkias minutes, išleidžia užbaigimą, kurio blocking_deadline_at terminas praėjo, prieš pradėdamas kitą išgavimo bandymą. Vėlesnė sėkmė atskirai pristatoma kaip šis įvykis.

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

Siunčiamas vieną kartą, kai kampanijos būsena pasikeičia iš running į completed, nesvarbu, ar baigėsi jos tvarkaraštis, ar visi kontaktai pasiekė galutines būsenas. Vykdytojo pakartotiniai bandymai nesiunčia kito įvykio. Šis organizacijos lygmens gyvavimo ciklo įvykis pristatomas tik organizacijos apimties galiniams taškams, o ne agento apimties galiniams taškams. Neribojantis.

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

Keturi rezultatų skaičiai nesutampa ir jų suma lygi contacts_total: completed apima sėkmingus kontaktus; no_answer apima galutinius nepavykusius arba išnaudotus kontaktus, kurių galutinis rezultatas buvo neatsakyta; failed apima visus kitus galutinius nepavykusius arba išnaudotus kontaktus; o remaining apima laukiančius, suplanuotus arba šiuo metu kontaktuojamus kontaktus. Kontaktas, laukiantis pakartotinio bandymo, yra remaining, net kai į naujausią bandymą nebuvo atsakyta. Vykstantys skambučiai suderinami prieš vienkartinę užbaigimo momentinę kopiją. started_at yra sukonfigūruota kampanijos pradžia arba kampanijos sukūrimo laikas, jei pradžia nebuvo sukonfigūruota.

issue.reported#

Siunčiamas, kai sukuriama problemos ataskaita — arba vartotojo pateikta iš valdymo skydelio (source: "user"), arba automatiškai skambučio vertinimo metu (source: "system"). Neribojantis.

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

Siunčiamas, kai problemos šablonas perduodamas ThunderPhone darbuotojų peržiūrai: po Pranešti ThunderPhone arba kai Taisyti su AI negali patvirtinti kliento pusėje atlikto pataisymo ir automatiškai nukreipia problemą. Šį įvykį gauna tik visos organizacijos galiniai taškai.

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

Tai pranešimas, o ne įrodymų rinkinys. Naudokite cluster_id, kad susietumėte jį su problemos šablonu. Žr. Pranešti ThunderPhone.

Bandomųjų skambučių įvykiai#

test-call.completed#

Siunčiamas, kai bandomojo skambučio vykdymas pasiekia galutinę būseną — completed arba failed, įskaitant vykdymus, kurie nepavyko paleidimo metu ir niekada nesukūrė skambučio. Neblokuojantis. Naudinga norint prijungti paketinius CI vykdymus prie pokalbių / pranešimų sistemų.

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

Įspėjimų įvykiai#

alert.triggered#

Siunčiamas, kai įspėjimo taisyklė, kurioje įjungtas kanalas Pristatyti į kūrėjų žiniatinklio kabliukus, viršija savo slenkstį. Neblokuojantis. Taisyklė suveikia vieną kartą ir tuomet laikosi savo atvėsimo laikotarpio, todėl nuolatinis pažeidimas sukuria po vieną įvykį kiekviename atvėsimo laikotarpio lange.

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

Taisyklių, metrikų, atvėsimo laikotarpių ir el. pašto / Slack kanalų kūrimą rasite Įspėjimų vadove.

Susiję#