Händelsekatalog

Alla webhook-händelsetyper som ThunderPhone skickar.

Varje webhook-kropp har ett type-fält vars värde är en av händelsetyperna på den här sidan. När du prenumererar på en slutpunkt måste arrayen events innehålla de händelsetyper du vill ha (eller vara tom för att prenumerera på allt — utom händelserna per tur telephony.turn / web.turn, som endast levereras till slutpunkter som anger dem uttryckligen).

Två leveranssätt hanterar dessa händelser:

• Endpoint-leveranser är alltid icke-blockerande aviseringar med återförsök: svara med valfri 2xx; kuvertet innehåller ett event_id för deduplicering.
• Blockerande utbyten körs endast via den äldre webhooken med en enda URL: begäran om konfiguration för telephony.incoming / web.incoming (nummer i webhookläge: 13 s inklusive ett återförsök; widgetnycklar i webhookläge: 10 s) och verktygsdirigering i webhookläge. Ditt svar formar det pågående samtalet.

Exempelnyttolaster nedan visar slutpunktskuvertet i dess överföringsordning (nycklar sorterade alfabetiskt: data, event_id, type); äldre leveranser innehåller samma data utan event_id.

Samtalshändelser#

telephony.incoming#

Skickas när ett inkommande samtal når ett av dina telefonnummer. Endpoint-leveranser är fire-and-forget-notifieringar som skickas för varje inkommande samtal, oavsett om numret är konfigurerat för en agent eller en webhook. Nummer utan en tilldelad agent får dessutom den blockerande konfigurationsbegäran på den äldre webhooken — se telephony.incoming / web.incoming för det fullständiga begäran-/svarsschemat.

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

telephony.complete#

Skickas när ett inkommande eller utgående telefonsamtal avslutas. Icke-blockerande. Innehåller transkriptionen, inspelnings-URL när den är tillgänglig och en faktureringssammanfattning. Se telephony.complete / web.complete för payload-schemat.

telephony.tool#

Skickas efter att ett telefonsamtal anropar ett funktionsverktyg. Icke-blockerande granskningsnotifiering — verktyget har redan körts när den här händelsen levereras; den omfattar dina egna funktionsverktyg och det inbyggda verktyget send_sms (inte andra inbyggda verktyg, kunskapsbasverktyg, verktyg för appanslutningar eller MCP-verktyg). För send_sms är både arguments.to och arguments.body [REDACTED]. Transkriptioner vid slutförande maskerar dem också; hämta innehållet och mottagaren från den organisationsomfattande SMS-resursen med hjälp av 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 är det körda resultatet: {"status": <http status>, "response": <your endpoint's JSON>} vid lyckat resultat, eller {"status": <status>, "error": "<message>"} vid fel.

telephony.turn#

Skickas medan ett telefonsamtal pågår, en gång för varje talbärande tur i takt med att den sker — agentens talade svar och uppringarens transkriberade turer. Gör att du kan följa den pågående konversationen via vanliga webhooks i stället för att polla GET /v1/calls/{call_id}/transcript. Icke-blockerande.

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

Motsvarigheten till telephony.incoming för webbkanalen, skickad när en session i en webbwidget eller ett mikrofonsamtalstest i byggaren startar. Endpoint-leveranser är fire-and-forget för varje webbsession. Publicerbara nycklar i mode="webhook" får dessutom den blockerande konfigurationsbegäran på den äldre webhooken — den blockerande begäran har en annan form (origin_domain, publishable_key_prefix; inga telefonnummer). 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 är alltid den bokstavliga strängen "web". För widgetsessioner i webhook-läge är to_number tomt (sessionens agentnummer tilldelas efter konfiguration); för mikrofonsamtalstest i byggaren är origin_domain och publishable_key_prefix tomma.

web.complete#

Motsvarigheten till telephony.complete för webbkanalen, som omfattar samtal i webbwidgeten (direction: "web") och mikrofonsamtalstest i byggaren (direction: "test"). Icke-blockerande. Samma payload-form som telephony.complete, plus origin_domain, med from_number satt till "web".

web.tool#

Motsvarigheten till telephony.tool för webbkanalen. data innehåller origin_domain i stället för from_number / to_number.

web.turn#

Motsvarigheten till telephony.turn för webbkanalen, som omfattar samtal i webbwidgeten och mikrofonsamtalstest i byggaren. Samma payload- form, med origin_domain i stället för from_number / to_number. Precis som telephony.turn kräver den en uttrycklig prenumeration — den levereras aldrig via en tom events-array.

call.transfer_completed#

Skickas en gång per samtal med det slutliga resultatet av en samtalsöverföring: en kall överföring eller den mänskliga brygga som en varm överföring lämnar kvar när agenten kopplas bort. Blockerar inte och levereras endast till slutpunkter (aldrig till den äldre webhooken med en enda URL). Den kommer efter samtalets telephony.complete: när operatören tar över samtalet eller överföringen misslyckas, eller när ThunderPhone har bryggat samtalet, när bryggan avslutas.

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

Samma värden finns på samtalsobjektet som transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds och transfer_bridge_total_cents. event_id är samma vid varje leverans för ett samtal, så en upprepad rapport skapar aldrig en andra händelse.

SMS-händelser#

SMS-händelser beskriver meddelanden som skickas via organisationens anslutna Twilio- eller Telnyx-konto. Meddelandetexten utelämnas och to maskeras. Hämta det organisationsomfattande meddelandet från GET /v1/sms/{message_id} när dess innehåll eller mottagare behövs.

sms.sent#

Skickas när kundens operatör accepterar en begäran om utgående SMS. Detta är inte ett leveranskvitto till en telefon.

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

Skickas efter ett permanent avslag från operatören, efter att tillfälliga återförsök har uttömts eller när utfallet är slutgiltigt okänt. error_code är en stabil ThunderPhone-kod och error_message anger kundåtgärden när en sådan är tillgänglig. status: "unknown" innebär att operatören kan ha accepterat SMS:et; stäm av det i operatörens logg eftersom ThunderPhone inte skickar om det automatiskt.

sms.received#

Reserverad för stöd för inkommande SMS. Inga sms.received-händelser skickas i den aktuella versionen. Konfiguration av webhookar för inkommande SMS hos operatören och signaturverifiering lanseras separat.

Rösthändelser#

Skapande av anpassade röster sker asynkront. Med dessa icke-blockerande händelser kan du reagera på ett slutgiltigt resultat i stället för att polla slutpunkten för klondetaljer.

voice.ready och voice.failed levereras endast till en organisationsomfattande slutpunkt med events: []. De kan inte väljas som explicita händelsefilter.

voice.ready#

Skickas när en anpassad röst har slutfört bearbetningen och kan tilldelas till 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#

Skickas när bearbetningen av en anpassad röst når ett permanent fel.

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

Skickas när en AI-graderingskörning slutförs för ett samtal. Icke-blockerande.

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

Skickas när extrahering av strukturerade data har slutförts, inklusive ett sent nytt försök efter telephony.complete / web.complete eller en manuell omkörning via POST /v1/calls/{call_id}/extract. Icke-blockerande.

I ett blockerande extraheringsläge väntar slutförandehändelsen normalt högst den 75 sekunder långa extraheringsbudgeten. Om extraheringsarbetsprocessen försvinner frigör produktionsslutförandedräneringen (var femte minut) ett slutförande vars blocking_deadline_at har passerat innan den startar ett nytt extraheringsförsök. En senare lyckad extrahering levereras separat som denna 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#

Skickas en gång när en kampanj går från running till completed, oavsett om dess schema avslutades eller alla kontakter nådde slutliga tillstånd. Försök från köraren skickar inte ytterligare en händelse. Denna livscykelhändelse på organisationsnivå levereras endast till endpoints på organisationsnivå, inte endpoints på agentnivå. Icke-blockerande.

{
  "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 fyra utfallsräkningarna är ömsesidigt uteslutande och summerar till contacts_total: completed innehåller lyckade kontakter; no_answer innehåller slutligt misslyckade eller uttömda kontakter vars slutliga utfall var inget svar; failed innehåller alla andra slutligt misslyckade eller uttömda kontakter; och remaining innehåller väntande, schemalagda eller kontakter som just nu rings upp. En kontakt som väntar på ett nytt försök är remaining, även när det senaste försöket inte fick något svar. Pågående samtal stäms av före ögonblicksbilden för slutförande som endast skickas en gång. started_at är kampanjens konfigurerade starttid eller tidpunkten då kampanjen skapades om ingen start konfigurerades.

issue.reported#

Skickas när en problemrapport skapas — antingen skickad av en användare från instrumentpanelen (source: "user") eller automatiskt genom samtalsgradering (source: "system"). Icke-blockerande.

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

Skickas när ett problemmönster skickas till ThunderPhone för granskning av personal: efter Rapportera till ThunderPhone, eller när Åtgärda med AI inte kan bekräfta en korrigering på kundsidan och automatiskt dirigerar problemet vidare. Endast organisationsomfattande endpoints tar emot denna 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"
}

Detta är en avisering, inte underlagspaketet. Använd cluster_id för att korrelera den med problemmönstret. Se Rapportera till ThunderPhone.

Händelser för testsamtal#

test-call.completed#

Skickas när en körning av testsamtal når en slutstatus — completed eller failed, inklusive körningar som misslyckades vid start och aldrig skapade ett samtal. Icke-blockerande. Användbart för att koppla batchkörningar i CI till dina chatt- och aviseringssystem.

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

Aviseringshändelser#

alert.triggered#

Skickas när en aviseringsregel med kanalen Leverera till utvecklarwebhooks aktiverad passerar sitt tröskelvärde. Icke-blockerande. En regel utlöses en gång och respekterar sedan sin cooldown, så en ihållande överträdelse ger en händelse per cooldownfönster.

{
  "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 guiden för aviseringar för att skapa regler, mätvärden, cooldowns och e-post- / Slack-kanalerna.

Migreringshändelser#

migration.call.complete#

Skickas när ett samtal som ringts via POST /v1/migrations/{id}/calls avslutas, oavsett vilken plattform som hanterade det. Icke-blockerande. Det kommer upp till cirka 5 minuter efter att samtalet avslutats. data innehåller alla fält från telephony.complete samt ett migration-block. Ett samtal som ThunderPhone ringde skickar också telephony.complete som vanligt, med samma call_id. Ett samtal på den andra plattformen som inte har avslutats efter 2 timmar, eller vars migrering har slutförts eller förlorat sin nyckel innan dess, skickas med status: "unknown" och utan transkription.

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

För ett vendor-samtal har ThunderPhone inga fakturerings- eller extraheringsdata: billable_minutes, billing_total_cents och extracted_data är null, product och voice är tomma, recording_mode är vendor och recording_url är den andra plattformens länk, när den gav en.

migration.rollback#

Skickas när en migrerings gradvisa övergång automatiskt flyttar tillbaka alla samtal till den andra plattformen: 3 samtal kunde inte ansluta till ThunderPhone inom 15 minuter, 2 samtal som skickades till ThunderPhone avslutades innan agenten svarade, eller ThunderPhones resultatfrekvens för uppgifter sjönk mer än det konfigurerade gapet under den andra plattformens. Icke-blockerande, en gång per återställning. Efteråt är ThunderPhones andel 0 % och migreringen pausas tills någon återupptar den på agentens flik Migration. Nyttolasten innehåller inga telefonnummer, transkript eller samtals-id:n.

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

Relaterat#