Katalog událostí

Všechny typy událostí webhooků, které ThunderPhone odesílá.

Každé tělo webhooku obsahuje pole type, jehož hodnota je jedním z typů událostí na této stránce. Když se přihlásíte k odběru koncového bodu, pole events musí obsahovat požadované typy událostí (nebo musí být prázdné, pokud se chcete přihlásit k odběru všeho — s výjimkou událostí pro jednotlivá kola telephony.turn / web.turn, které jsou doručovány pouze koncovým bodům, jež je výslovně uvádějí).

Tyto události jsou doručovány dvěma způsoby:

• Doručení do endpointu jsou vždy neblokující oznámení s opakovanými pokusy: odpovězte libovolným kódem 2xx; obálka obsahuje event_id pro deduplikaci.
• Blokující výměny probíhají pouze na starším webhooku s jedinou URL: při požadavku na konfiguraci telephony.incoming / web.incoming (čísla v režimu webhooku: 13 s včetně jednoho opakovaného pokusu; klíče widgetu v režimu webhooku: 10 s) a při odesílání nástroje v režimu webhooku. Vaše odpověď ovlivňuje průběh živého hovoru.

Ukázkové datové obsahy níže zobrazují obálku koncového bodu v pořadí přenášeném po síti (klíče jsou seřazeny abecedně: data, event_id, type); starší doručení obsahují stejná data bez event_id.

Události hovorů#

telephony.incoming#

Odesílá se, když příchozí hovor dorazí na jedno z vašich telefonních čísel. Doručení na endpoint jsou oznámení typu fire-and-forget odesílaná pro každý příchozí hovor bez ohledu na to, zda je číslo nakonfigurováno pro agenta nebo webhook. Čísla bez přiřazeného agenta navíc obdrží blokující požadavek na konfiguraci na starším webhooku — úplné schéma požadavku / odpovědi naleznete 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#

Odesílá se po skončení příchozího nebo odchozího telefonního hovoru. Neblokující. Zahrnuje přepis, adresu URL nahrávky, je-li k dispozici, a souhrn vyúčtování. Schéma datové struktury naleznete v telephony.complete / web.complete.

telephony.tool#

Odesílá se poté, co telefonní hovor vyvolá funkční nástroj. Neblokující oznámení pro audit — nástroj již byl spuštěn v okamžiku doručení této události; zahrnuje vaše vlastní funkční nástroje a vestavěný nástroj send_sms (nikoli jiné vestavěné nástroje, nástroje znalostní báze, připojení aplikací ani nástroje MCP). Pro send_sms jsou arguments.to i arguments.body hodnotou [REDACTED]. Přepisy po dokončení hovoru je také redigují; obsah a příjemce načtěte ze zdroje SMS v rozsahu organizace pomocí message_id z odpovědi.

{
  "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 výsledek provedení: při úspěchu {"status": <http status>, "response": <your endpoint's JSON>} nebo při selhání {"status": <status>, "error": "<message>"}.

telephony.turn#

Odesílá se během probíhajícího telefonního hovoru, jednou pro každý tah obsahující řeč, jakmile nastane — mluvené dokončení odpovědi agenta a přepsané tahy volajícího. Umožňuje sledovat živou konverzaci prostřednictvím běžných webhooků namísto dotazování GET /v1/calls/{call_id}/transcript. Neblokující.

{
  "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 pro webový kanál, odesílaný při zahájení relace webového widgetu nebo testovacího hovoru mikrofonu v editoru. Doručení na endpoint jsou oznámení typu fire-and-forget pro každou webovou relaci. Publikovatelné klíče v mode="webhook" navíc obdrží blokující požadavek na konfiguraci na starším webhooku — tento blokující požadavek má jinou strukturu (origin_domain, publishable_key_prefix; žádná telefonní čísla). Viz 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 vždy doslovná hodnota "web". U relací widgetu v režimu webhooku je to_number prázdné (číslo agenta relace se přiřadí po konfiguraci); u testovacích hovorů mikrofonu v editoru jsou origin_domain a publishable_key_prefix prázdné.

web.complete#

Ekvivalent telephony.complete pro webový kanál, zahrnující hovory webového widgetu (direction: "web") a testovací hovory mikrofonu v editoru (direction: "test"). Neblokující. Stejná struktura dat jako u telephony.complete, navíc s origin_domain, přičemž from_number je nastaveno na "web".

web.tool#

Ekvivalent telephony.tool pro webový kanál. data obsahuje origin_domain namísto from_number / to_number.

web.turn#

Ekvivalent telephony.turn pro webový kanál, zahrnující hovory webového widgetu a testovací hovory mikrofonu v editoru. Stejná struktura dat, s origin_domain namísto from_number / to_number. Stejně jako telephony.turn vyžaduje explicitní odběr — nikdy se nedoručuje prostřednictvím prázdného pole events.

call.transfer_completed#

Odesílá se jednou za hovor s konečným výsledkem přepojení hovoru: studeného přepojení nebo spojení mezi lidmi, které po odpojení agenta zůstane po teplém přepojení. Neblokuje zpracování a doručuje se pouze do endpointů (nikdy do staršího webhooku s jedinou URL). Přichází po události telephony.complete hovoru: jakmile operátor převezme hovor nebo přepojení selže, případně, když ThunderPhone hovor propojil, po ukončení spojení.

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

Stejné hodnoty jsou v objektu hovoru jako transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds a transfer_bridge_total_cents. event_id je při každém doručení pro hovor stejné, takže opakované hlášení nikdy nevytvoří druhou událost.

Události SMS#

Události SMS popisují zprávy odeslané prostřednictvím účtu Twilio nebo Telnyx připojeného k organizaci. Tělo zprávy je vynecháno a to je začerněno. Zprávu v rozsahu organizace načtěte z GET /v1/sms/{message_id}, pokud potřebujete její obsah nebo příjemce.

sms.sent#

Odesílá se, když operátor zákazníka přijme požadavek na odchozí SMS. Nejde o potvrzení doručení do zařízení.

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

Odesílá se po trvalém odmítnutí operátorem, po vyčerpání opakovaných pokusů při přechodných chybách nebo pokud je výsledek definitivně neznámý. error_code je stabilní kód ThunderPhone a error_message uvádí akci zákazníka, pokud je k dispozici. status: "unknown" znamená, že operátor mohl SMS přijmout; ověřte ji v protokolu operátora, protože ThunderPhone ji automaticky znovu neodešle.

sms.received#

Vyhrazeno pro podporu příchozích SMS. V aktuální verzi se neodesílají žádné události sms.received. Konfigurace webhooku příchozího operátora a ověření podpisu budou vydány samostatně.

Hlasové události#

Vytváření vlastního hlasu probíhá asynchronně. Tyto neblokující události vám umožňují reagovat na konečný výsledek namísto dotazování koncového bodu s podrobnostmi klonu.

voice.ready a voice.failed se doručují pouze do koncového bodu pro celou organizaci s events: []. Nelze je vybrat jako explicitní filtry událostí.

voice.ready#

Odesílá se, když vlastní hlas dokončí zpracování a lze jej přiřadit agentovi.

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

Odesílá se, když zpracování vlastního hlasu skončí trvalým selháním.

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

Události kvality#

call.graded#

Odesílá se po dokončení běhu hodnocení AI pro hovor. Neblokující.

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

Odesílá se po úspěšném dokončení extrakce strukturovaných dat, včetně pozdního opakování po telephony.complete / web.complete nebo ručního opětovného spuštění prostřednictvím POST /v1/calls/{call_id}/extract. Neblokující.

V blokujícím režimu extrakce událost dokončení obvykle nečeká déle než 75sekundový limit pro extrakci. Pokud dojde ke ztrátě procesu pracovníka extrakce, produkční vyprazdňování finalizace (každých pět minut) uvolní dokončení, jehož blocking_deadline_at uplynul, ještě před zahájením dalšího pokusu o extrakci. Pozdější úspěch je doručen samostatně jako tato událost.

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

Odešle se jednou, když kampaň přejde ze stavu running do completed, ať už její plán skončil, nebo všechny kontakty dosáhly koncových stavů. Opakované pokusy runneru neodesílají další událost. Tato událost životního cyklu na úrovni organizace se doručuje pouze do koncových bodů s rozsahem organizace, nikoli do koncových bodů s rozsahem agenta. Neblokující.

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

Čtyři počty výsledků se vzájemně vylučují a jejich součet odpovídá hodnotě contacts_total: completed obsahuje úspěšné kontakty; no_answer obsahuje koncové neúspěšné/vyčerpané kontakty, jejichž konečným výsledkem byla neodpověď; failed obsahuje všechny ostatní koncové neúspěšné/vyčerpané kontakty; a remaining obsahuje čekající, naplánované nebo právě volané kontakty. Kontakt čekající na opakovaný pokus je remaining, i když jeho poslední pokus skončil bez odpovědi. Probíhající hovory jsou odsouhlaseny před jednorázovým snímkem dokončení. started_at je nakonfigurovaný začátek kampaně, nebo čas vytvoření kampaně, pokud začátek nebyl nakonfigurován.

issue.reported#

Odešle se při vytvoření hlášení problému — buď jej uživatel odešle z řídicího panelu (source: "user"), nebo jej automaticky vytvoří hodnocení hovoru (source: "system"). Neblokující.

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

Odešle se, když je vzorec problému odeslán ThunderPhone ke kontrole týmem: po kliknutí na Nahlásit ThunderPhoneu nebo když funkce Opravit pomocí AI nemůže potvrdit opravu na straně zákazníka a problém automaticky předá. Tuto událost přijímají pouze koncové body pro celou organizaci.

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

Jde o oznámení, nikoli o balíček důkazů. Pomocí cluster_id jej propojte se vzorem problému. Viz Nahlásit ThunderPhoneu.

Události testovacích hovorů#

test-call.completed#

Odesílá se, když testovací běh hovoru dosáhne konečného stavu — completed nebo failed, včetně běhů, které selhaly při spuštění a nikdy nevytvořily hovor. Neblokující. Užitečné pro propojení dávkových běhů CI s vašimi systémy chatu a oznámení.

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

Události upozornění#

alert.triggered#

Odesílá se, když pravidlo upozornění s povoleným kanálem Doručovat do webhooků pro vývojáře překročí svůj práh. Neblokující. Pravidlo se spustí jednou a poté respektuje dobu ochlazení, takže trvalé překročení vytvoří jednu událost za každé okno doby ochlazení.

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

Informace o vytváření pravidel, metrikách, dobách ochlazení a kanálech e-mail / Slack najdete v průvodci upozorněními.

Události migrace#

migration.call.complete#

Odesílá se po ukončení hovoru uskutečněného prostřednictvím POST /v1/migrations/{id}/calls, bez ohledu na to, která platforma jej zpracovala. Neblokuje. Doručí se až přibližně 5 minut po ukončení hovoru. data obsahuje všechna pole z telephony.complete a blok migration. Hovor uskutečněný službou ThunderPhone také jako obvykle odešle telephony.complete se stejným call_id. Hovor na druhé platformě, který neskončil ani po 2 hodinách nebo jehož migrace byla dokončena či nejprve ztratila svůj klíč, se odešle se status: "unknown" a bez přepisu.

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

Pro hovor vendor nemá ThunderPhone žádné údaje o účtování ani extrakci: billable_minutes, billing_total_cents a extracted_data jsou null, product a voice jsou prázdné, recording_mode je vendor a recording_url je odkaz druhé platformy, pokud jej poskytla.

migration.rollback#

Odesílá se, když postupné přepínání migrace samo přesune všechny hovory zpět na druhou platformu: 3 hovory se během 15 minut nepodařilo připojit k ThunderPhone, 2 hovory odeslané do ThunderPhone skončily před odpovědí agenta nebo míra úspěšnosti výsledků úloh ThunderPhone klesla pod míru druhé platformy o více než nastavený rozdíl. Neblokující, jednou při každém vrácení zpět. Poté je podíl ThunderPhone 0 % a migrace je pozastavena, dokud ji někdo znovu nespustí na kartě Migrace agenta. Datová část neobsahuje žádná telefonní čísla, přepisy ani ID hovorů.

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

Související#