Eseménykatalógus

A ThunderPhone által kibocsátott összes webhookesemény-típus.

Minden webhook törzse tartalmaz egy type mezőt, amelynek értéke az oldalon szereplő eseménytípusok egyike. Amikor feliratkozik egy végpontra, az events tömbnek tartalmaznia kell a kívánt eseménytípusokat (vagy üresnek kell lennie, ha mindenre fel szeretne iratkozni — kivéve a körönkénti eseményeket telephony.turn / web.turn, amelyeket csak azoknak a végpontoknak kézbesítünk, amelyek kifejezetten megnevezik őket).

Ezeket az eseményeket két kézbesítési mód továbbítja:

• Végpontkézbesítések mindig nem blokkoló értesítések újrapróbálkozásokkal: válaszoljon bármely 2xx kóddal; a boríték deduplikáláshoz tartalmaz egy event_id azonosítót.
• A blokkoló adatcserék csak a régi, egyetlen URL-es webhookon futnak: a telephony.incoming / web.incoming konfigurációs kérés (webhook módú számok: 13 mp, egy újrapróbálkozással együtt; webhook módú widgetkulcsok: 10 mp), valamint a webhook módú eszközhívás. Az Ön válasza alakítja az élő hívást.

Az alábbi példaterhek a végpontborítékot a vezetékes sorrendjében mutatják (a kulcsok ábécérendben: data, event_id, type); a régi kézbesítések ugyanazt a data adatot tartalmazzák event_id nélkül.

Hívási események#

telephony.incoming#

Akkor kerül elküldésre, amikor egy bejövő hívás eléri az Ön egyik telefonszámát. A végpontkézbesítések minden bejövő híváshoz elküldött, azonnali válasz nélküli értesítések, függetlenül attól, hogy a szám ügynökhöz vagy webhookhoz van-e konfigurálva. A hozzárendelt ügynök nélküli számok emellett a régi webhookon kapják meg a blokkoló konfigurációs kérést — a teljes kérés-/válaszsémát itt találja: 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#

Akkor kerül elküldésre, amikor egy bejövő vagy kimenő telefonhívás véget ér. Nem blokkoló. Tartalmazza az átiratot, a felvétel URL-jét, ha elérhető, valamint a számlázási összesítőt. A hasznos teher sémáját itt találja: telephony.complete / web.complete.

telephony.tool#

Akkor kerül elküldésre, miután egy telefonhívás meghív egy függvényeszközt. Nem blokkoló naplózási értesítés — az eszköz már lefutott, amikor ez az esemény kézbesítésre kerül; lefedi az Ön saját függvényeszközeit és a beépített send_sms eszközt (de nem más beépített, tudásbázis-, alkalmazáskapcsolati vagy MCP-eszközöket). A send_sms esetében mind az arguments.to, mind az arguments.body értéke [REDACTED]. A befejezési átiratok is kitakarják ezeket; a tartalmat és a címzettet a szervezeti hatókörű SMS-erőforrásból kérheti le a válasz message_id értékével.

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

A response a végrehajtott eredmény: siker esetén {"status": <http status>, "response": <your endpoint's JSON>}, hiba esetén pedig {"status": <status>, "error": "<message>"}.

telephony.turn#

Telefonhívás folyamatban léte közben kerül elküldésre, minden beszédet tartalmazó fordulóhoz annak megtörténtekor — az ügynök kimondott válaszaihoz és a hívó átírt fordulóihoz. Lehetővé teszi az élő beszélgetés követését egyszerű webhookokon keresztül, a GET /v1/calls/{call_id}/transcript lekérdezése helyett. Nem blokkoló.

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

A telephony.incoming webcsatornás megfelelője, amely akkor kerül elküldésre, amikor egy webes widget-munkamenet vagy egy szerkesztőbeli mikrofonteszt-hívás elindul. A végpontkézbesítések minden webes munkamenethez azonnali válasz nélküli értesítések. A mode="webhook" módban lévő publikálható kulcsok emellett a régi webhookon kapják meg a blokkoló konfigurációs kérést — ennek a blokkoló kérésnek eltérő struktúrája van (origin_domain, publishable_key_prefix; nincsenek telefonszámok). Lásd: 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"
}

A from_number mindig a szó szerinti "web" érték. Webhook módú widget-munkameneteknél a to_number üres (a munkamenet ügynökszáma a konfiguráció után kerül hozzárendelésre); szerkesztőbeli mikrofonteszt-hívásoknál az origin_domain és a publishable_key_prefix üres.

web.complete#

A telephony.complete webcsatornás megfelelője, amely a webes widget-hívásokat (direction: "web") és a szerkesztőbeli mikrofonteszt-hívásokat (direction: "test") fedi le. Nem blokkoló. A hasznos teher struktúrája megegyezik a telephony.complete struktúrájával, az origin_domain mezővel kiegészítve, a from_number pedig "web" értékre van állítva.

web.tool#

A telephony.tool webcsatornás megfelelője. A data a from_number / to_number helyett az origin_domain értéket tartalmazza.

web.turn#

A telephony.turn webcsatornás megfelelője, amely a webes widget-hívásokat és a szerkesztőbeli mikrofonteszt-hívásokat fedi le. A hasznos teher struktúrája megegyezik, de a from_number / to_number helyett az origin_domain szerepel. A telephony.turn eseményhez hasonlóan ehhez is kifejezett feliratkozás szükséges — üres events tömbön keresztül soha nem kerül kézbesítésre.

call.transfer_completed#

Hívásonként egyszer küldve, egy hívásátirányítás végső eredményével: hideg átirányítás esetén, illetve a meleg átirányítás után fennmaradó emberi kapcsolattal, miután az ügynök kilép. Nem blokkoló, és csak végpontokra kerül kézbesítésre (a régi, egyetlen URL-es webhookra soha). A hívás telephony.complete eseménye után érkezik: amikor a szolgáltató átveszi a hívást vagy az átirányítás sikertelen, illetve amikor ThunderPhone áthidalta a hívást, az áthidalás befejeződésekor.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

Ugyanezek az értékek a hívásobjektumon is elérhetők transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds és transfer_bridge_total_cents néven. Az event_id minden kézbesítéskor azonos egy adott hívásnál, ezért egy ismételt jelentés nem hoz létre második eseményt.

SMS-események#

Az SMS-események a szervezet csatlakoztatott Twilio- vagy Telnyx-fiókján keresztül küldött üzeneteket írják le. Az üzenet törzse kimarad, a to pedig ki van takarva. Amikor szüksége van a tartalomra vagy a címzettre, kérje le a szervezeti hatókörű üzenetet a GET /v1/sms/{message_id} végponton.

sms.sent#

Akkor kerül elküldésre, amikor az ügyfél szolgáltatója elfogad egy kimenő SMS-kérést. Ez nem a készülékre történő kézbesítésről szóló visszaigazolás.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Végleges szolgáltatói elutasítás után, az átmeneti hibák miatti újrapróbálkozások kimerülésekor, illetve akkor kerül elküldésre, ha az eredmény véglegesen ismeretlen. Az error_code stabil ThunderPhone-kód, az error_message pedig megadja az ügyfél teendőjét, ha rendelkezésre áll. A status: "unknown" azt jelenti, hogy a szolgáltató esetleg elfogadta az SMS-t; egyeztesse ezt a szolgáltatói naplóban, mert a ThunderPhone nem küldi el újra automatikusan.

sms.received#

Bejövő SMS-ek támogatásához van fenntartva. A jelenlegi kiadásban nem kerülnek kibocsátásra sms.received események. A bejövő szolgáltatói webhook konfigurációja és az aláírás ellenőrzése külön érkezik.

Hangesemények#

Az egyéni hang létrehozása aszinkron. Ezek a nem blokkoló események lehetővé teszik, hogy lekérdezés helyett egy végleges eredményre reagáljon a hangklón részleteinek végpontján.

A voice.ready és a voice.failed csak egy szervezetszintű, events: [] beállítású végpontra érkezik. Nem választhatók ki explicit eseményszűrőként.

voice.ready#

Akkor kerül elküldésre, amikor az egyéni hang feldolgozása befejeződik, és hozzárendelhető egy ügynökhöz.

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

Akkor kerül elküldésre, amikor az egyéni hang feldolgozása végleges hibával leáll.

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

Minőségi események#

call.graded#

Akkor kerül elküldésre, amikor egy hívás AI-értékelési futtatása befejeződik. Nem blokkoló.

{
  "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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Akkor kerül elküldésre, amikor a strukturált adatkinyerés sikeresen befejeződik, beleértve a telephony.complete / web.complete utáni késői újrapróbálkozást vagy a POST /v1/calls/{call_id}/extract útján indított manuális újrafuttatást. Nem blokkoló.

Blokkoló kinyerési módban a befejezési esemény általában legfeljebb a 75 másodperces kinyerési keretre vár. Ha a kinyerési munkafolyamat elvész, az éles környezetbeli véglegesítési feldolgozás (ötpercenként) kibocsát egy befejezési eseményt, amelynek blocking_deadline_at értéke lejárt, mielőtt újabb kinyerési kísérletet indítana. Egy későbbi siker külön eseményként kerül kézbesítésre.

{
  "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": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Egyszer kerül elküldésre, amikor egy kampány állapota running értékről completed értékre vált, függetlenül attól, hogy az ütemezése ért véget, vagy minden kapcsolat elérte a végállapotot. A futtató újrapróbálkozásai nem bocsátanak ki újabb eseményt. Ez a szervezetszintű életciklus-esemény csak szervezeti hatókörű végpontokhoz kerül kézbesítésre, ügynökszintű végpontokhoz nem. Nem blokkoló.

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

A négy eredményszám egymást kizárja, és összegük contacts_total: a completed a sikeres kapcsolatokat tartalmazza; a no_answer azon végleges sikertelen/kimerült kapcsolatokat tartalmazza, amelyek végső eredménye válasz nélküli volt; a failed minden más végleges sikertelen/kimerült kapcsolatot tartalmaz; a remaining pedig a függőben lévő, ütemezett vagy éppen hívott kapcsolatokat tartalmazza. Az újrapróbálkozásra váró kapcsolat remaining, még akkor is, ha a legutóbbi kísérlet válasz nélküli volt. A folyamatban lévő hívások egyeztetése az egyszeri befejezési pillanatfelvétel előtt történik. A started_at a konfigurált kampányindítási idő, vagy a kampány létrehozásának időpontja, ha nem volt indítási idő konfigurálva.

issue.reported#

Akkor kerül elküldésre, amikor létrejön egy problémajelentés — akár egy felhasználó rögzíti a kezelőfelületről (source: "user"), akár a hívásértékelés hozza létre automatikusan (source: "system"). Nem blokkoló.

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

Akkor kerül elküldésre, amikor egy problémamintát munkatársi felülvizsgálatra küldenek a ThunderPhonehoz: a Jelentés a ThunderPhonenak művelet után, vagy amikor a Javítás AI-val nem tud ügyféloldali javítást megerősíteni, és automatikusan továbbítja a problémát. Ezt az eseményt csak szervezetszintű végpontok kapják meg.

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

Ez egy értesítés, nem a bizonyítékcsomag. A cluster_id használatával kapcsolhatja össze a problémamintával. Lásd: Jelentés a ThunderPhonenak.

Teszthívási események#

test-call.completed#

Akkor kerül elküldésre, amikor egy teszthívás-futtatás végső állapotba kerül — completed vagy failed, beleértve azokat a futtatásokat is, amelyek az indításkor meghiúsultak, és soha nem hoztak létre hívást. Nem blokkoló. Hasznos a kötegelt CI-futtatások csevegési/értesítési rendszereihez való kapcsolásához.

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

Riasztási események#

alert.triggered#

Akkor kerül elküldésre, amikor egy riasztási szabály, amelynél engedélyezve van a Kézbesítés fejlesztői webhookokra csatorna, átlépi a küszöbértékét. Nem blokkoló. Egy szabály egyszer aktiválódik, majd betartja a várakozási idejét, így egy tartós küszöbsértés várakozási időablakonként egy eseményt hoz létre.

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

A szabályok, metrikák, várakozási idők, valamint az e-mail- és Slack-csatornák létrehozásáról lásd a Riasztások útmutatót.

Migrációs események#

migration.call.complete#

Akkor kerül elküldésre, amikor egy POST /v1/migrations/{id}/calls végponton keresztül indított hívás véget ér, függetlenül attól, hogy melyik platform kezelte. Nem blokkoló. A hívás befejezése után legfeljebb körülbelül 5 perccel érkezik meg. A data tartalmazza a telephony.complete összes mezőjét, valamint egy migration blokkot. A ThunderPhone által indított hívás a szokásos módon telephony.complete eseményt is küld, ugyanazzal a call_id értékkel. A másik platformon futó hívás, amely 2 óra elteltével sem ért véget, vagy amelynek migrációja előbb befejeződött, illetve elvesztette a kulcsát, status: "unknown" értékkel és átirat nélkül kerül elküldésre.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

vendor hívás esetén a ThunderPhone nem rendelkezik számlázási vagy kinyerési adatokkal: a billable_minutes, a billing_total_cents és az extracted_data értéke null, a product és a voice üres, a recording_mode értéke vendor, a recording_url pedig a másik platform hivatkozása, ha megadott ilyet.

migration.rollback#

Akkor kerül elküldésre, amikor egy migráció fokozatos átváltása önállóan minden hívást visszahelyez a másik platformra: 15 percen belül 3 hívásnak nem sikerült kapcsolódnia a ThunderPhone-hoz, 2 ThunderPhone-hoz irányított hívás az AI-ügynök válasza előtt véget ért, vagy a ThunderPhone feladateredmény-aránya a konfigurált különbségnél nagyobb mértékben maradt el a másik platformétól. Nem blokkoló, visszaállításonként egyszer kerül elküldésre. Ezt követően a ThunderPhone részesedése 0%, és a migráció szünetel, amíg valaki újra nem indítja azt az AI-ügynök Migráció lapján. A payload nem tartalmaz telefonszámokat, átiratokat vagy hívásazonosítókat.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

Kapcsolódó elemek#