Hændelseskatalog

Alle webhook-hændelsestyper, som ThunderPhone udsender.

Hver webhook-brødtekst har et type-felt, hvis værdi er en af hændelsestyperne på denne side. Når du abonnerer på et endepunkt, skal events-arrayet indeholde de hændelsestyper, du ønsker (eller være tomt for at abonnere på alt — undtagen hændelser pr. tur telephony.turn / web.turn, som kun leveres til endepunkter, der angiver dem eksplicit).

To leveringsformer transporterer disse hændelser:

• Endpoint-leveringer er altid ikke-blokerende notifikationer med gentagelser: svar med enhver 2xx; konvolutten indeholder et event_id til deduplikering.
• Blokerende udvekslinger kører kun på den ældre webhook med enkelt URL: anmodningen om konfiguration for telephony.incoming / web.incoming (numre i webhooktilstand: 13 s inklusive ét gentagelsesforsøg; widgetnøgler i webhooktilstand: 10 s) og værktøjsdistribuering i webhooktilstand. Dit svar former det aktive opkald.

Eksempelpayloadene nedenfor viser endepunktkonvolutten i dens trådrækkefølge (nøgler sorteret alfabetisk: data, event_id, type); ældre leveringer indeholder de samme data uden event_id.

Opkaldshændelser#

telephony.incoming#

Sendes, når et indgående opkald når et af dine telefonnumre. Endpoint-leveringer er fire-and-forget-notifikationer, der sendes for alle indgående opkald, uanset om nummeret er agentkonfigureret eller webhookkonfigureret. Numre uden en tildelt agent modtager desuden den blokerende konfigurationsanmodning på den ældre webhook — se telephony.incoming / web.incoming for det fulde skema for anmodning og svar.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

Sendes, når et indgående eller udgående telefoniopkald afsluttes. Ikke-blokerende. Indeholder transskriptionen, optagelses-URL'en, når den er tilgængelig, og faktureringsoversigten. Se telephony.complete / web.complete for payload-skemaet.

telephony.tool#

Sendes, efter et telefoniopkald kalder et funktionsværktøj. Ikke-blokerende revisionsnotifikation — værktøjet er allerede kørt, når denne hændelse leveres; den dækker dine egne funktionsværktøjer og det indbyggede send_sms-værktøj (ikke andre indbyggede værktøjer, vidensbaseværktøjer, appforbindelser eller MCP-værktøjer). For send_sms er både arguments.to og arguments.body [REDACTED]. Transskriptioner ved afslutning redigerer også disse; hent indholdet og modtageren fra den organisationsafgrænsede SMS-ressource ved hjælp af svarets message_id.

{
  "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 er det udførte resultat: {"status": <http status>, "response": <your endpoint's JSON>} ved succes eller {"status": <status>, "error": "<message>"} ved fejl.

telephony.turn#

Sendes, mens et telefoniopkald er i gang, én gang for hver talebærende tur, efterhånden som den sker — agentens talte fuldførelser og opkalderens transskriberede ture. Gør det muligt at følge den live samtale via almindelige webhooks i stedet for at polle GET /v1/calls/{call_id}/transcript. Ikke-blokerende.

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

Webkanalens ækvivalent til telephony.incoming, der sendes, når en webwidget-session eller et builder-mikrofontestopkald starter. Endpoint-leveringer er fire-and-forget for hver websession. Publicerbare nøgler i mode="webhook" modtager desuden den blokerende konfigurationsanmodning på den ældre webhook — denne blokerende anmodning har en anden struktur (origin_domain, publishable_key_prefix; ingen telefonnumre). Se 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 er altid den bogstavelige værdi "web". For widgetsessioner i webhooktilstand er to_number tomt (sessionens agentnummer tildeles efter konfiguration); for builder-mikrofontestopkald er origin_domain og publishable_key_prefix tomme.

web.complete#

Webkanalens ækvivalent til telephony.complete, der dækker opkald fra webwidgets (direction: "web") og builder-mikrofontestopkald (direction: "test"). Ikke-blokerende. Samme payload-struktur som telephony.complete, plus origin_domain, med from_number sat til "web".

web.tool#

Webkanalens ækvivalent til telephony.tool. data indeholder origin_domain i stedet for from_number / to_number.

web.turn#

Webkanalens ækvivalent til telephony.turn, der dækker opkald fra webwidgets og builder-mikrofontestopkald. Samme payload- struktur, med origin_domain i stedet for from_number / to_number. Ligesom telephony.turn kræver den et eksplicit abonnement — den leveres aldrig via et tomt events-array.

call.transfer_completed#

Sendes én gang pr. opkald med det endelige resultat af en opkaldsoverførsel: en kold overførsel eller den forbindelse mellem mennesker, som en varm overførsel efterlader, når agenten træder ud. Ikke-blokerende og leveres kun til slutpunkter (aldrig til den ældre webhook med én URL). Den ankommer efter opkaldets telephony.complete: når operatøren overtager opkaldet, eller overførslen mislykkes, eller, når ThunderPhone har oprettet forbindelse i opkaldet, når forbindelsen afsluttes.

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

De samme værdier findes på opkaldsobjektet som transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds og transfer_bridge_total_cents. event_id er den samme ved hver levering for et opkald, så en gentaget rapport aldrig opretter en ny hændelse.

SMS-hændelser#

SMS-hændelser beskriver beskeder, der sendes via organisationens tilknyttede Twilio- eller Telnyx-konto. Beskedens brødtekst udelades, og to maskeres. Hent den organisationsafgrænsede besked fra GET /v1/sms/{message_id}, når dens indhold eller modtager er nødvendig.

sms.sent#

Sendes, når kundens operatør accepterer en udgående SMS-anmodning. Dette er ikke en leveringskvittering fra enheden.

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

Sendes efter en permanent afvisning fra operatøren, efter midlertidige genforsøg er opbrugt, eller når resultatet endeligt er ukendt. error_code er en stabil ThunderPhone-kode, og error_message angiver kundens handling, når den er tilgængelig. status: "unknown" betyder, at operatøren muligvis har accepteret SMS'en; afstem den i operatørens log, fordi ThunderPhone ikke gensender den automatisk.

sms.received#

Reserveret til understøttelse af indgående SMS. Der udsendes ingen sms.received-hændelser i den aktuelle udgivelse. Konfiguration af indgående webhooks fra operatøren og signaturverifikation leveres separat.

Stemmehændelser#

Oprettelse af brugerdefinerede stemmer er asynkron. Disse ikke-blokerende hændelser gør det muligt at reagere på et endeligt resultat i stedet for at forespørge slutpunktet for klonedetaljer.

voice.ready og voice.failed leveres kun til et organisationsdækkende slutpunkt med events: []. De kan ikke vælges som eksplicitte hændelsesfiltre.

voice.ready#

Sendes, når en brugerdefineret stemme er færdigbehandlet og kan tildeles til en agent.

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

Sendes, når behandlingen af en brugerdefineret stemme ender med en permanent fejl.

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

Kvalitetshændelser#

call.graded#

Sendes, hver gang en AI-bedømmelse fuldføres for et opkald. Blokerer ikke.

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

Sendes, hver gang udtrækning af strukturerede data fuldføres uden fejl, herunder en sen genprøve efter telephony.complete / web.complete eller en manuel genkørsel via POST /v1/calls/{call_id}/extract. Blokerer ikke.

I en blokerende udtrækningstilstand venter fuldførelseshændelsen normalt højst på udtrækningsbudgettet på 75 sekunder. Hvis udtrækningsarbejderprocessen går tabt, frigiver produktionens afslutningsdræning, der kører hvert femte minut, en fuldførelse, hvis blocking_deadline_at er overskredet, før den starter endnu et udtrækningsforsøg. En senere succes leveres separat som denne hændelse.

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

Sendes én gang, når en kampagne går fra running til completed, uanset om dens tidsplan sluttede, eller alle kontakter nåede terminale tilstande. Forsøg fra køreren udsender ikke endnu en hændelse. Denne livscyklushændelse på organisationsniveau leveres kun til organisationsomfattende slutpunkter, ikke til agentspecifikke slutpunkter. Blokerer ikke.

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

De fire resultatantal er gensidigt udelukkende og summerer til contacts_total: completed indeholder gennemførte kontakter; no_answer indeholder terminalt mislykkede eller udtømte kontakter, hvis endelige resultat var intet svar; failed indeholder alle andre terminalt mislykkede eller udtømte kontakter; og remaining indeholder afventende, planlagte eller aktuelt ringende kontakter. En kontakt, der venter på et nyt forsøg, er remaining, også når dens seneste forsøg ikke fik svar. Igangværende opkald afstemmes før øjebliksbilledet for den engangsudsendte fuldførelse. started_at er kampagnens konfigurerede start eller tidspunktet for oprettelse af kampagnen, når der ikke var konfigureret en start.

issue.reported#

Sendes, når en problemrapport oprettes — enten indsendt af en bruger fra dashboardet (source: "user") eller automatisk af opkaldsbedømmelse (source: "system"). Blokerer ikke.

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

Sendes, når et problemmønster sendes til ThunderPhone til medarbejdergennemgang: efter Rapporter til ThunderPhone, eller når Ret med AI ikke kan bekræfte en rettelse på kundesiden og automatisk videresender problemet. Kun organisationsomfattende slutpunkter modtager denne hændelse.

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

Dette er en notifikation, ikke dokumentationspakken. Brug cluster_id til at knytte den til problemmønsteret. Se Rapporter til ThunderPhone.

Testopkaldshændelser#

test-call.completed#

Sendes, når et testopkaldskørsel når en endelig status — completed eller failed, herunder kørsler, der mislykkedes ved start og aldrig oprettede et opkald. Ikke-blokerende. Nyttig til at koble CI-batchkørsler til dine chat- og notifikationssystemer.

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

Advarselshændelser#

alert.triggered#

Sendes, når en advarselsregel med kanalen Lever til udviklerwebhooks aktiveret overskrider sin tærskel. Ikke-blokerende. En regel udløses én gang og overholder derefter sin nedkølingsperiode, så en vedvarende overskridelse producerer én hændelse pr. nedkølingsvindue.

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

Se vejledningen til advarsler for at oprette regler, metrikker, nedkølingsperioder og e-mail- / Slack-kanaler.

Migreringshændelser#

migration.call.complete#

Sendes, når et opkald, der er foretaget via POST /v1/migrations/{id}/calls, afsluttes, uanset hvilken platform der foretog det. Ikke-blokerende. Det ankommer op til ca. 5 minutter efter opkaldet afsluttes. data har alle felter fra telephony.complete plus en migration-blok. Et opkald foretaget af ThunderPhone sender også telephony.complete som normalt med det samme call_id. Et opkald på den anden platform, som ikke er afsluttet efter 2 timer, eller hvis migrering blev afsluttet eller mistede sin nøgle først, sendes med status: "unknown" og uden transskription.

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

For et vendor-opkald har ThunderPhone ingen fakturerings- eller udtræksdata: billable_minutes, billing_total_cents og extracted_data er null, product og voice er tomme, recording_mode er vendor, og recording_url er den anden platforms link, når den angav et.

migration.rollback#

Sendes, når en migrations gradvise skift automatisk flytter alle opkald tilbage til den anden platform: 3 opkald kunne ikke oprette forbindelse til ThunderPhone inden for 15 minutter, 2 opkald sendt til ThunderPhone sluttede, før agenten svarede, eller ThunderPhones opgaveudførelsesrate faldt mere end den konfigurerede forskel under den anden platforms. Ikke-blokerende, én gang pr. tilbagerulning. Derefter er ThunderPhones andel 0 %, og migreringen er sat på pause, indtil nogen genoptager den på agentens fane Migrering. Dataobjektet indeholder ingen telefonnumre, transskriptioner eller opkalds-id'er.

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

Relateret#