Katalog dogodkov

Vse vrste dogodkov webhook, ki jih pošilja ThunderPhone.

Vsako telo webhooka ima polje type, katerega vrednost je ena od vrst dogodkov na tej strani. Ko se naročite na končno točko, mora polje events vsebovati želene vrste dogodkov (ali pa je prazno za naročanje na vse — razen dogodkov za posamezni korak telephony.turn / web.turn, ki se dostavijo samo končnim točkam, ki jih izrecno navedejo).

Ta dogodka se dostavljata na dva načina:

• Dostave na končno točko so vedno neblokirajoča obvestila z ponovnimi poskusi: odgovorite s katerim koli 2xx; ovojnica vsebuje event_id za odpravljanje podvojenih dogodkov.
• Blokirajoče izmenjave se izvajajo samo prek zastarelega webhooka z enim URL-jem: zahteva za konfiguracijo telephony.incoming / web.incoming (številke v načinu webhook in ključi gradnika, časovna omejitev 10 s) ter odpošiljanje orodij v načinu webhook tool dispatch. Vaš odgovor oblikuje klic v živo.

Spodnji primeri podatkovnih bremen prikazujejo ovojnico končne točke v njenem vrstnem redu na žici (ključi so razvrščeni po abecedi: data, event_id, type); zastarele dostave vsebujejo enake data brez event_id.

Dogodki klicev#

telephony.incoming#

Pošlje se, ko dohodni klic doseže eno od vaših telefonskih številk. Dostave na končne točke so obvestila brez čakanja na odgovor, poslana za vsak dohodni klic, ne glede na to, ali je številka konfigurirana za agenta ali spletni kavelj. Številke brez dodeljenega agenta dodatno prejmejo blokirajočo zahtevo za konfiguracijo na podedovanem spletnem kavlju — celotno shemo zahteve/odziva najdete v 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#

Pošlje se, ko se dohodni ali odhodni telefonski klic konča. Ne blokira. Vključuje prepis, URL posnetka, kadar je na voljo, in povzetek obračuna. Shemo koristnega tovora najdete v telephony.complete / web.complete.

telephony.tool#

Pošlje se, ko telefonski klic prikliče funkcijsko orodje. Ne blokira; gre za obvestilo za revizijo — orodje je ob dostavi tega dogodka že izvedeno; vključuje vaša lastna funkcijska orodja (ne vgrajenih orodij, orodij zbirke znanja, povezav aplikacij ali orodij MCP).

{
  "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 izvedbe: {"status": <http status>, "response": <your endpoint's JSON>} ob uspehu ali {"status": <status>, "error": "<message>"} ob neuspehu.

telephony.turn#

Pošlje se medtem, ko telefonski klic poteka, enkrat za vsak govorni obrat, takoj ko nastane — govorjene dokončane izjave agenta in prepisani obrati klicatelja. Omogoča spremljanje pogovora v živo prek običajnih spletnih kavljev namesto anketiranja GET /v1/calls/{call_id}/transcript. Ne blokira.

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

Spletni ekvivalent dogodka telephony.incoming, poslan, ko se začne seja spletnega gradnika ali preizkusni klic mikrofona v graditelju. Dostave na končne točke so obvestila brez čakanja na odgovor za vsako spletno sejo. Objavljivi ključi v mode="webhook" dodatno prejmejo blokirajočo zahtevo za konfiguracijo na podedovanem spletnem kavlju — ta blokirajoča zahteva ima drugačno obliko (origin_domain, publishable_key_prefix; brez telefonskih številk). Glejte 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 je vedno dobesedna vrednost "web". Za seje gradnika v načinu spletnega kavlja je to_number prazen (številka agenta seje se dodeli po konfiguraciji); za preizkusne klice mikrofona v graditelju sta origin_domain in publishable_key_prefix prazna.

web.complete#

Spletni ekvivalent dogodka telephony.complete, ki vključuje klice spletnega gradnika (direction: "web") in preizkusne klice mikrofona v graditelju (direction: "test"). Ne blokira. Ima enako obliko koristnega tovora kot telephony.complete, dodatno pa še origin_domain, pri čemer je from_number nastavljen na "web".

web.tool#

Spletni ekvivalent dogodka telephony.tool. data vsebuje origin_domain namesto from_number / to_number.

web.turn#

Spletni ekvivalent dogodka telephony.turn, ki vključuje klice spletnega gradnika in preizkusne klice mikrofona v graditelju. Ima enako obliko koristnega tovora, z origin_domain namesto from_number / to_number. Tako kot telephony.turn zahteva izrecno naročnino — nikoli se ne dostavi prek praznega polja events.

Glasovni dogodki#

Ustvarjanje glasov po meri je asinhrono. Ti neblokirni dogodki vam omogočajo, da se odzovete na končni rezultat, namesto da bi izvajali poizvedbe na končni točki s podrobnostmi klona.

voice.ready in voice.failed sta dostavljena samo na končno točko za celotno organizacijo z events: []. Ni ju mogoče izbrati kot izrecna filtra dogodkov.

voice.ready#

Poslano, ko se glas po meri konča obdelovati in ga je mogoče dodeliti 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#

Poslano, ko obdelava glasu po meri doseže trajno napako.

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

Dogodki kakovosti#

call.graded#

Pošlje se vsakič, ko se za klic zaključi ocenjevanje z AI. Ne blokira.

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

Pošlje se vsakič, ko se strukturirano pridobivanje podatkov uspešno zaključi, vključno s poznim ponovnim poskusom po telephony.complete / web.complete ali ročnim ponovnim zagonom prek POST /v1/calls/{call_id}/extract. Ne blokira.

V načinu blokirajočega pridobivanja dogodek zaključka običajno čaka največ 75 sekund, kolikor znaša proračun za pridobivanje. Če se proces delavca za pridobivanje izgubi, produkcijsko dokončanje (vsakih pet minut) sprosti zaključek, katerega blocking_deadline_at je potekel, preden začne nov poskus pridobivanja. Poznejši uspeh se ločeno dostavi kot ta dogodek.

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

Pošlje se enkrat, ko se kampanja premakne iz running v completed, ne glede na to, ali se je njen urnik končal ali so vsi stiki dosegli končna stanja. Ponovni poskusi izvajalnika ne pošljejo novega dogodka. Ta dogodek življenjskega cikla na ravni organizacije je dostavljen samo končnim točkam z obsegom organizacije, ne končnim točkam z obsegom agenta. Ne blokira.

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

Štiri števce izidov se med seboj izključujejo in seštejejo v contacts_total: completed vsebuje uspešne stike; no_answer vsebuje končne neuspešne oziroma izčrpane stike, katerih končni izid je bil neodgovorjen klic; failed vsebuje vse druge končne neuspešne oziroma izčrpane stike; remaining pa vsebuje čakajoče, načrtovane ali trenutno klicane stike. Stik, ki čaka na ponovni poskus, je remaining, tudi kadar je bil njegov najnovejši poskus neodgovorjen klic. Klici v teku se uskladijo pred enkratnim posnetkom zaključka. started_at je konfigurirani začetek kampanje ali čas ustvarjanja kampanje, kadar začetek ni bil konfiguriran.

issue.reported#

Pošlje se, ko je ustvarjeno poročilo o težavi — bodisi ga uporabnik vloži z nadzorne plošče (source: "user") bodisi ga ocenjevanje klica ustvari samodejno (source: "system"). Ne blokira.

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

Pošlje se, ko se vzorec težave pošlje ThunderPhone v pregled osebja: po Prijavi ThunderPhone ali kadar Fix with AI ne more potrditi popravka na strani stranke in težavo samodejno usmeri naprej. Ta dogodek prejmejo samo končne točke na ravni celotne 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"
}

To je obvestilo, ne sveženj dokazov. Uporabite cluster_id, da ga povežete z vzorcem težave. Oglejte si Prijavi ThunderPhone.

Dogodki testnih klicev#

test-call.completed#

Pošlje se, ko izvajanje testnega klica doseže končno stanje — completed ali failed, vključno z izvajanji, ki niso uspela ob zagonu in niso nikoli ustvarila klica. Neblokirajoče. Uporabno za povezovanje paketnih izvajanj CI z vašimi sistemi za klepet/obvestila.

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

Dogodki opozoril#

alert.triggered#

Pošlje se, ko pravilo opozorila z omogočenim kanalom Dostavi v spletne kljuke za razvijalce preseže svoj prag. Neblokirajoče. Pravilo se sproži enkrat in nato upošteva obdobje ohlajanja, zato trajna kršitev ustvari en dogodek na obdobje ohlajanja.

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

Za ustvarjanje pravil, metrike, obdobja ohlajanja ter e-poštne kanale / kanale Slack glejte vodnik za opozorila.

Povezano#