Sündmuste kataloog

Kõik veebikonksu sündmusetüübid, mida ThunderPhone väljastab.

Iga webhooki keha sisaldab välja type, mille väärtus on üks sellel lehel toodud sündmusetüüpidest. Kui tellid lõpp-punkti, peab massiiv events sisaldama soovitud sündmusetüüpe (või olema tühi, et tellida kõik sündmused — välja arvatud voorupõhised sündmused telephony.turn / web.turn, mis saadetakse ainult lõpp-punktidele, kus need on selgesõnaliselt nimetatud).

Neid sündmusi edastatakse kahes stiilis:

• Lõpp-punkti edastused on alati mitteblokeerivad teavitused koos uuesti proovimistega: vasta mis tahes 2xx-koodiga; ümbrik sisaldab duplikaatide eemaldamiseks event_id.
• Blokeerivad vahetused toimuvad ainult pärandatud ühe URL-iga webhookis: telephony.incoming / web.incoming seadistustaotlus (webhooki režiimis numbrid ja vidina võtmed, 10 s ajalõpp) ning webhooki režiimis tööriista väljakutse. Sinu vastus kujundab aktiivset kõnet.

Allolevad näidiskoormad näitavad lõpp-punkti ümbrikku selle juhtmejärjekorras (võtmed on sorditud tähestikuliselt: data, event_id, type); pärandedastused sisaldavad sama data ilma väljata event_id.

Kõnesündmused#

telephony.incoming#

Saadetakse, kui sissetulev kõne jõuab ühele sinu telefoninumbrile. Lõpp-punkti edastused on vastust ootamata teavitused iga sissetuleva kõne kohta, olenemata sellest, kas number on häälagendi või webhooki jaoks seadistatud. Määratud häälagendita numbrid saavad lisaks pärandwebhooki kaudu blokeeriva konfiguratsioonipäringu — täieliku päringu- ja vastuseskeemi leiad siit: 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#

Saadetakse, kui sissetulev või väljaminev telefonikõne lõpeb. Mitteblokeeriv. Sisaldab transkriptsiooni, salvestise URL-i, kui see on saadaval, ning arvelduse kokkuvõtet. Vaata andmekoormuse skeemi siit: telephony.complete / web.complete.

telephony.tool#

Saadetakse pärast seda, kui telefonikõne käivitab funktsioonitööriista. Mitteblokeeriv auditeerimisteavitus — tööriist on selle sündmuse edastamise ajaks juba käivitatud; see hõlmab sinu enda funktsioonitööriistu, mitte sisseehitatud, teadmusbaasi, rakenduseühenduse ega MCP tööriistu.

{
  "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 käivitatud tulemus: õnnestumise korral {"status": <http status>, "response": <your endpoint's JSON>}, ebaõnnestumise korral {"status": <status>, "error": "<message>"}.

telephony.turn#

Saadetakse telefonikõne ajal üks kord iga kõnet sisaldava vooru kohta — häälagendi öeldud lõpetused ja helistaja transkribeeritud voorud. Võimaldab jälgida reaalajas vestlust tavaliste webhookide kaudu, selle asemel et küsitleda GET /v1/calls/{call_id}/transcript. Mitteblokeeriv.

{
  "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 veebikanali vaste, mis saadetakse siis, kui veebividina seanss või koosturi mikrofonitestkõne algab. Lõpp-punkti edastused on vastust ootamata teavitused iga veebiseansi kohta. Režiimis mode="webhook" olevad avaldatavad võtmed saavad lisaks pärandwebhooki kaudu blokeeriva konfiguratsioonipäringu — selle blokeeriva päringu kuju on erinev (origin_domain, publishable_key_prefix; telefoninumbrid puuduvad). Vaata 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 alati sõneliteral "web". Webhooki režiimis veebividina seansside puhul on to_number tühi (seansi häälagendi number määratakse pärast konfigureerimist); koosturi mikrofonitestkõnede puhul on origin_domain ja publishable_key_prefix tühjad.

web.complete#

telephony.complete veebikanali vaste, mis hõlmab veebividina kõnesid (direction: "web") ja koosturi mikrofonitestkõnesid (direction: "test"). Mitteblokeeriv. Andmekoormuse struktuur on sama mis telephony.complete puhul, lisaks on olemas origin_domain ning from_number väärtuseks on "web".

web.tool#

telephony.tool veebikanali vaste. data sisaldab välja from_number / to_number asemel välja origin_domain.

web.turn#

telephony.turn veebikanali vaste, mis hõlmab veebividina kõnesid ja koosturi mikrofonitestkõnesid. Andmekoormuse struktuur on sama, kuid from_number / to_number asemel kasutatakse välja origin_domain. Nagu telephony.turn, nõuab see otsest tellimust — seda ei edastata kunagi tühja events massiivi kaudu.

Häälsündmused#

Kohandatud hääle loomine on asünkroonne. Need mitteblokeerivad sündmused võimaldavad sul reageerida lõpptulemusele, selle asemel et küsitleda klooni üksikasjade lõpp-punkti.

voice.ready ja voice.failed saadetakse ainult organisatsiooniülesele lõpp-punktile, millel on events: []. Neid ei saa valida otseste sündmusefiltritena.

voice.ready#

Saadetakse, kui kohandatud hääl lõpetab töötlemise ja selle saab määrata agendile.

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

Saadetakse, kui kohandatud hääle töötlemine lõpeb püsiva tõrkega.

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

Kvaliteedisündmused#

call.graded#

Saadetakse iga kord, kui kõne AI-hindamise käitamine lõpeb. Ei blokeeri.

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

Saadetakse iga kord, kui struktureeritud andmete eraldamine lõpeb edukalt, sealhulgas hilise korduskatse järel pärast telephony.complete / web.complete või käsitsi uuesti käivitamisel läbi POST /v1/calls/{call_id}/extract. Ei blokeeri.

Blokeerivas eraldusrežiimis ootab lõpetamissündmus tavaliselt kuni 75-sekundilist eraldamise ajavahemikku. Kui eraldustöötlusprotsess kaob, väljastab tootmiskeskkonna lõpetamise tühjendusprotsess (iga viie minuti järel) lõpetamise, mille blocking_deadline_at on möödunud, enne kui alustab uut eralduskatset. Hilisem õnnestumine saadetakse eraldi selle sündmusena.

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

Saadetakse üks kord, kui kampaania liigub olekust running olekusse completed, olenemata sellest, kas selle ajakava lõppes või kõik kontaktid jõudsid lõppolekusse. Käivitaja korduskatsed ei saada uut sündmust. See organisatsioonitasandi elutsüklisündmus saadetakse ainult organisatsioonipõhistele lõpp-punktidele, mitte häälagendipõhistele lõpp-punktidele. Ei blokeeri.

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

Neli tulemuste arvu ei kattu ja nende summa on contacts_total: completed sisaldab edukaid kontakte; no_answer sisaldab lõppolekusse jõudnud ebaõnnestunud või katsetega ammendatud kontakte, mille lõpptulemuseks oli vastuse puudumine; failed sisaldab kõiki muid lõppolekusse jõudnud ebaõnnestunud või katsetega ammendatud kontakte; ning remaining sisaldab ootel, ajastatud või praegu helistatavaid kontakte. Korduskatset ootav kontakt on remaining, isegi kui selle viimane katse jäi vastuseta. Käimasolevad kõned kooskõlastatakse enne ühekordset lõpetamise hetkeseisu. started_at on kampaania konfigureeritud algusaeg või kampaania loomise aeg, kui algusaega ei konfigureeritud.

issue.reported#

Saadetakse, kui luuakse probleemiaruanne — kas kasutaja esitab selle töölaualt (source: "user") või see luuakse automaatselt kõne hindamise käigus (source: "system"). Ei blokeeri.

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

Saadetakse, kui probleemimuster saadetakse ThunderPhone'ile töötajate ülevaatuseks: pärast Teavita ThunderPhone'i kasutamist või kui Paranda tehisintellektiga ei suuda kliendipoolset parandust kinnitada ja suunab probleemi automaatselt edasi. Selle sündmuse saavad ainult organisatsiooniülesed lõpp-punktid.

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

See on teavitus, mitte tõendite kogum. Kasuta cluster_id, et siduda see probleemimustriga. Vaata Teavita ThunderPhone'i.

Testkõne sündmused#

test-call.completed#

Saadetakse, kui testkõne käitamine jõuab lõppolekusse — completed või failed, sealhulgas käitamised, mis ebaõnnestusid käivitamisel ega loonud kunagi kõnet. Mitteblokeeriv. Kasulik partii-CI käitamiste ühendamiseks sinu vestlus- ja teavitussüsteemidega.

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

Hoiatuse sündmused#

alert.triggered#

Saadetakse, kui hoiatusreegel, mille kanal Edasta arendaja veebikonksudele on lubatud, ületab oma lävendi. Mitteblokeeriv. Reegel käivitub ühe korra ja järgib seejärel oma jahtumisperioodi, seega tekitab püsiv rikkumine ühe sündmuse iga jahtumisperioodi akna kohta.

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

Reeglite, mõõdikute, jahtumisperioodide ning e-posti- ja Slacki kanalite loomise kohta vaata hoiatuste juhendit.

Seotud#