Hendelseskatalog

Alle webhook-hendelsestyper ThunderPhone sender ut.

Hver webhook-brødtekst har et type-felt med en verdi som er én av hendelsestypene på denne siden. Når du abonnerer på et endepunkt, må events-matrisen inneholde hendelsestypene du ønsker (eller være tom for å abonnere på alt — med unntak av hendelsene per tur telephony.turn / web.turn, som bare leveres til endepunkter som navngir dem eksplisitt).

Disse hendelsene leveres på to måter:

• Endepunktleveringer er alltid ikke-blokkerende varsler med nye forsøk: svar med en hvilken som helst 2xx; konvolutten inneholder en event_id for deduplisering.
• Blokkerende utvekslinger kjøres kun på eldre webhook med én URL: konfigurasjonsforespørselen for telephony.incoming / web.incoming (numre i webhook-modus: 13 s inkludert ett nytt forsøk; widgetnøkler i webhook-modus: 10 s) og verktøysutsendelse i webhook-modus. Svaret ditt former den aktive samtalen.

Eksempellastene nedenfor viser endepunktkonvolutten i overføringsrekkefølge (nøkler sortert alfabetisk: data, event_id, type); eldre leveringer har samme data uten event_id.

Anropshendelser#

telephony.incoming#

Sendes når et innkommende anrop når ett av dine telefonnumre. Leveringer til endepunkter er fire-and-forget-varsler som sendes for hvert innkommende anrop, enten nummeret er agentkonfigurert eller webhook-konfigurert. Numre uten en tilordnet agent mottar i tillegg den blokkerende konfigurasjonsforespørselen på den eldre webhooken — se telephony.incoming / web.incoming for hele skjemaet for forespørsel / 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 innkommende eller utgående telefonianrop avsluttes. Ikke-blokkerende. Inkluderer transkripsjonen, URL til opptaket når tilgjengelig, og en faktureringsoversikt. Se telephony.complete / web.complete for nyttelastskjemaet.

telephony.tool#

Sendes etter at et telefonianrop påkaller et funksjonsverktøy. Ikke-blokkerende revisjonsvarsel — verktøyet er allerede kjørt når denne hendelsen leveres; den dekker dine egne funksjonsverktøy og det innebygde send_sms-verktøyet (ikke andre innebygde verktøy, kunnskapsbaseverktøy, appkoblinger eller MCP-verktøy). For send_sms er både arguments.to og arguments.body [REDACTED]. Transkripsjoner ved fullføring skjuler også disse; hent innholdet og mottakeren fra den organisasjonsavgrensede SMS-ressursen ved å bruke 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 resultatet som ble utført: {"status": <http status>, "response": <your endpoint's JSON>} ved suksess, eller {"status": <status>, "error": "<message>"} ved feil.

telephony.turn#

Sendes mens et telefonianrop pågår, én gang for hver talebaserte tur etter hvert som den skjer — agentens talte fullføringer og innringerens transkriberte turer. Lar deg følge samtalen direkte via vanlige webhooks i stedet for å hente status gjentatte ganger fra GET /v1/calls/{call_id}/transcript. Ikke-blokkerende.

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

Nettkanalens tilsvarende hendelse til telephony.incoming, sendt når en nettwidget-økt eller et mikrofonsamtaletest fra byggeren starter. Leveringer til endepunkter er fire-and-forget for hver nettøkt. Publiserbare nøkler i mode="webhook" mottar i tillegg den blokkerende konfigurasjonsforespørselen på den eldre webhooken — den blokkerende forespørselen har en annen form (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 alltid den bokstavelige verdien "web". For widgetøkter i webhook-modus er to_number tomt (øktens agentnummer tilordnes etter konfigurasjon); for mikrofonsamtaletester i byggeren er origin_domain og publishable_key_prefix tomme.

web.complete#

Nettkanalens tilsvarende hendelse til telephony.complete, som dekker nettwidgetanrop (direction: "web") og mikrofonsamtaletester i byggeren (direction: "test"). Ikke-blokkerende. Samme nyttelastform som telephony.complete, i tillegg til origin_domain, med from_number satt til "web".

web.tool#

Nettkanalens tilsvarende hendelse til telephony.tool. data inneholder origin_domain i stedet for from_number / to_number.

web.turn#

Nettkanalens tilsvarende hendelse til telephony.turn, som dekker nettwidgetanrop og mikrofonsamtaletester i byggeren. Samme nyttelastform, med origin_domain i stedet for from_number / to_number. I likhet med telephony.turn krever den et eksplisitt abonnement — den leveres aldri gjennom en tom events-matrise.

call.transfer_completed#

Sendes én gang per samtale med det endelige utfallet av en samtaleoverføring: en blindoverføring eller broen mellom menneskene som en varm overføring etterlater når stemmeagenten kobler seg fra. Ikke-blokkerende, og leveres bare til endepunkter (aldri til den eldre webhooken med én URL). Den kommer etter samtalens telephony.complete: når operatøren overtar samtalen eller overføringen mislykkes, eller, når ThunderPhone har opprettet broen i samtalen, når broen avsluttes.

{
  "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 verdiene finnes på samtaleobjektet 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 en samtale, så en gjentatt rapport produserer aldri en ny hendelse.

SMS-hendelser#

SMS-hendelser beskriver meldinger som sendes via organisasjonens tilkoblede Twilio- eller Telnyx-konto. Meldingsinnholdet utelates, og to er sensurert. Hent den organisasjonsavgrensede meldingen fra GET /v1/sms/{message_id} når du trenger innholdet eller mottakeren.

sms.sent#

Sendes når kundens operatør godtar en utgående SMS-forespørsel. Dette er ikke en leveringsbekreftelse til håndsettet.

{
  "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 etter et permanent avslag fra operatøren, når midlertidige forsøk er oppbrukt, eller når utfallet er endelig ukjent. error_code er en stabil ThunderPhone-kode, og error_message angir kundehandlingen når den er tilgjengelig. status: "unknown" betyr at operatøren kan ha godtatt SMS-en; avstem den i operatørloggen fordi ThunderPhone ikke sender den på nytt automatisk.

sms.received#

Reservert for støtte for innkommende SMS. Det sendes ingen sms.received- hendelser i den nåværende versjonen. Konfigurasjon av webhook for innkommende meldinger fra operatøren og signaturverifisering lanseres separat.

Talehendelser#

Opprettelse av egendefinerte stemmer er asynkron. Disse ikke-blokkerende hendelsene lar deg reagere på et endelig resultat i stedet for å hente status gjentatte ganger fra detaljendepunktet for kloning.

voice.ready og voice.failed leveres bare til et organisasjonsomfattende endepunkt med events: []. De kan ikke velges som eksplisitte hendelsesfiltre.

voice.ready#

Sendes når en egendefinert stemme er ferdig behandlet og kan tilordnes 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 av en egendefinert stemme får en permanent feil.

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

Kvalitetshendelser#

call.graded#

Sendes hver gang en KI-vurderingskjøring fullføres for en samtale. Ikke-blokkerende.

{
  "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 uttrekk av strukturerte data fullføres, inkludert et forsinket nytt forsøk etter telephony.complete / web.complete eller en manuell nykjøring via POST /v1/calls/{call_id}/extract. Ikke-blokkerende.

I en blokkerende uttrekksmodus venter fullføringshendelsen normalt ikke lenger enn uttrekksbudsjettet på 75 sekunder. Hvis uttrekksarbeidsprosessen går tapt, frigir produksjonsdreneringen for fullføring (hvert femte minutt) en fullføring der blocking_deadline_at er passert, før den starter et nytt uttrekksforsøk. En senere vellykket kjøring leveres separat som denne hendelsen.

{
  "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 kampanje går fra running til completed, enten planen er avsluttet eller alle kontakter har nådd endelige tilstander. Nye forsøk fra kjøreren sender ikke en ny hendelse. Denne livssyklushendelsen på organisasjonsnivå leveres bare til endepunkter med organisasjonsomfang, ikke til endepunkter med agentomfang. Ikke-blokkerende.

{
  "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 utfallstallene er gjensidig utelukkende og summerer seg til contacts_total: completed inneholder vellykkede kontakter; no_answer inneholder endelige mislykkede/oppbrukte kontakter der det siste utfallet var intet svar; failed inneholder alle andre endelige mislykkede/oppbrukte kontakter; og remaining inneholder ventende, planlagte eller kontakter som ringes akkurat nå. En kontakt som venter på et nytt forsøk er remaining, selv når det siste forsøket ikke ble besvart. Aktive samtaler avstemmes før det engangs fullføringsøyeblikksbildet opprettes. started_at er den konfigurerte kampanjestarten, eller tidspunktet kampanjen ble opprettet hvis ingen start var konfigurert.

issue.reported#

Sendes når en problemmelding opprettes — enten registrert av en bruker fra dashbordet (source: "user") eller automatisk gjennom samtalevurdering (source: "system"). Ikke-blokkerende.

{
  "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 for gjennomgang av ansatte: etter Rapporter til ThunderPhone, eller når Løs med KI ikke kan bekrefte en retting på kundesiden og ruter problemet automatisk. Bare organisasjonsomfattende endepunkter mottar denne hendelsen.

{
  "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 et varsel, ikke bevispakken. Bruk cluster_id for å knytte det til problemmønsteret. Se Rapporter til ThunderPhone.

Testanropshendelser#

test-call.completed#

Sendes når en testanropskjøring når en sluttstatus — completed eller failed, inkludert kjøringer som mislyktes ved oppstart og aldri opprettet et anrop. Ikke-blokkerende. Nyttig for å koble CI-kjøringer i batch til chat- og varslingssystemene dine.

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

Varslingshendelser#

alert.triggered#

Sendes når en varslingsregel med kanalen Lever til utviklerwebhooks aktivert passerer terskelen sin. Ikke-blokkerende. En regel utløses én gang og respekterer deretter nedkjølingsperioden, så et vedvarende avvik produserer én hendelse per nedkjølingsvindu.

{
  "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 veiledningen for varslinger for å opprette regler, metrikker, nedkjølingsperioder og e-post- / Slack-kanalene.

Migreringshendelser#

migration.call.complete#

Sendes når en samtale som er ringt gjennom POST /v1/migrations/{id}/calls avsluttes, uavhengig av hvilken plattform som foretok den. Ikke-blokkerende. Den kommer opptil omtrent 5 minutter etter at samtalen avsluttes. data har alle feltene i telephony.complete pluss en migration-blokk. En samtale som ThunderPhone foretok, sender også telephony.complete som vanlig, med samme call_id. En samtale på den andre plattformen som ikke er avsluttet etter 2 timer, eller der migreringen ble fullført eller mistet nøkkelen sin først, sendes med status: "unknown" og uten transkripsjon.

{
  "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 en vendor-samtale har ThunderPhone ingen fakturerings- eller uttrekksdata: billable_minutes, billing_total_cents og extracted_data er null, product og voice er tomme, recording_mode er vendor, og recording_url er lenken fra den andre plattformen når den oppga en.

migration.rollback#

Sendes når en migrerings gradvise bytte automatisk flytter alle samtaler tilbake til den andre plattformen: 3 samtaler klarte ikke å koble til ThunderPhone innen 15 minutter, 2 samtaler sendt til ThunderPhone ble avsluttet før agenten svarte, eller ThunderPhones oppgaveutfallsrate falt mer enn det konfigurerte avviket under den andre plattformens. Ikke-blokkerende, én gang per tilbakeføring. Etter dette er ThunderPhones andel 0 %, og migreringen er satt på pause til noen gjenopptar den i agentens Migrering-fane. Nyttelasten inneholder ingen telefonnumre, transkripsjoner eller samtale-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"
}

Relatert#