Händelsekatalog

Varje webhook-innehåll 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 events-arrayen innehålla de händelsetyper du vill ha (eller vara tom för att prenumerera på allt). Dessa händelser skickas på två sätt:

Slutpunktsleveranser är alltid icke-blockerande aviseringar med återförsök: svara med valfri 2xx; omslaget innehåller ett event_id för deduplicering.
Blockerande utbyten körs endast på den äldre enkel-URL-webhooken: konfigurationsbegäran telephony.incoming / web.incoming (nummer i webhook-läge och widgetnycklar, 10 s timeout) samt verktygsdirigering i webhook-läge. Ditt svar påverkar det pågående samtalet.

Exempel på nyttolaster nedan visar slutpunktsomslaget 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. Leveranser till slutpunkten är fire-and-forget-aviseringar 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 schemat för begäran/svar.

{
  "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. Inkluderar transkriptionen, inspelnings-URL när den är tillgänglig och faktureringssammanfattningen. Se telephony.complete / web.complete för schemat för nyttolasten.

`telephony.tool`

Skickas efter att ett telefonsamtal anropar ett funktionsverktyg. Icke-blockerande granskningsavisering — verktyget har redan körts när denna händelse levereras; den omfattar dina egna funktionsverktyg (inte inbyggda verktyg, verktyg för kunskapsbaser, appanslutningar eller MCP-verktyg).

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

`web.incoming`

Webbkanalens motsvarighet till telephony.incoming, som skickas när en session i en webbwidget eller ett mikrofontestsamtal i byggaren startar. Leveranser till slutpunkten ä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 struktur (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 det bokstavliga värdet "web". För widgetsessions i webhook-läge är to_number tomt (sessionens agentnummer tilldelas efter konfigurationen); för mikrofontestsamtal i byggaren är origin_domain och publishable_key_prefix tomma.

`web.complete`

Webbkanalens motsvarighet till telephony.complete, som omfattar samtal i webbwidgetar (direction: "web") och mikrofontestsamtal i byggaren (direction: "test"). Icke-blockerande. Samma struktur för nyttolasten som telephony.complete, plus origin_domain, med from_number inställt på "web".

På den äldre webhooken med en enda URL rapporteras mikrofontestsamtal i byggaren historiskt som telephony.complete — endast samtal med direction: "web" använder typen web.complete där. Slutpunktssystemet mappar både webb- och testsamtal till web.*. Historiska nyttolaster kan innehålla de äldre direction-värdena widget eller mic.

`web.tool`

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

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 regelbundet fråga slutpunkten för klondetaljer.

`voice.ready`

Skickas när en anpassad röst har bearbetats klart och kan tilldelas 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 få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"
}

Fält	Typ	Beskrivning
`voice.id`	string	Offentligt id för anpassad röst
`voice.name`	string	Röstvärde för agenten i formatet `custom:<public_id>`
`voice.display_name`	string	Röstnamn för organisationen
`voice.language`	string	Klonens enda språkkod
`voice.gender`	string	`male`, `female` eller en tom sträng
`voice.status`	string	`ready` för `voice.ready`; `failed` för `voice.failed`
`voice.failure_reason`	string	Tomt vid lyckad bearbetning; information om bearbetningsfel vid fel
`voice.created_at`, `voice.updated_at`	timestamp	ISO 8601-tidsstämplar
`reason`	string	Felinformation; finns endast för `voice.failed`

Kvalitetshändelser

`call.graded`

Skickas när en AI-granskningskörning slutförs för ett samtal. Blockerar inte.

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

Fält	Typ	Beskrivning
`grade.id`	integer	Betygs-id
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` eller `no_conversation`
`grade.summary`	string	Sammanfattning i ett stycke
`grade.detected_issues`	array	Problemsträngar som hittades av granskaren
`grade.status`	string	Alltid `completed` — endast slutförda körningar skickas
`grade.grader_model`	string	Vilken granskarmodell som skapade resultatet (t.ex. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Ett samtal kan granskas fler än en gång — ett snabbt heuristiskt betyg följs ofta av ett fullständigt modellbetyg när inspelningen är tillgänglig, och manuella omgranskningar är möjliga. Varje slutförd körning skickar sin egen call.graded-händelse; behandla den senaste graded_at som auktoritativ.

`issue.reported`

Skickas när en problemrapport skapas — antingen inrapporterad av en användare från instrumentpanelen (source: "user") eller automatiskt genom samtalsgranskning (source: "system"). Blockerar inte.

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

Fält	Typ	Beskrivning
`issue_report.severity`	string	`critical`, `warning` eller `info`
`issue_report.status`	string	`open` eller `resolved`
`issue_report.source`	string	`user` (inrapporterad från instrumentpanelen) eller `system` (skapad av granskning)

Omgranskning av ett samtal bygger om dess systemgenererade problemrapporter, vilket skickar issue.reported igen för de återskapade rapporterna. Deduplicera efter call_id + title om du bara vill ha en notifiering per underliggande problem.

Händelser för testsamtal

`test-call.completed`

Skickas när en testsamtalskörning når en slutstatus — completed eller failed, inklusive körningar som misslyckades vid start och aldrig skapade ett samtal. Blockerar inte. Användbart för att koppla batchkörningar i CI till dina chatt-/notifieringssystem.

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

Fält	Typ	Beskrivning
`test_call_run.target_type`	string	`agent` eller `phone_number`
`test_call_run.target_id`	integer	Agent-id:t eller telefonnummer-id:t som körningen riktades mot, enligt `target_type`
`test_call_run.status`	string	`completed` eller `failed`
`test_call_run.call_id`	integer \| null	`null` när körningen misslyckades innan ett samtal ringdes
`test_call_run.error_message`	string	Tom vid lyckad körning

Varningshändelser

`alert.triggered`

Skickas när en varningsregel med kanalen Leverera till utvecklarwebhooks aktiverad passerar sitt tröskelvärde. Blockerar inte. En regel utlöses en gång och följer sedan sin cooldownperiod, så en ihållande avvikelse genererar 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"
}

Fält	Typ	Beskrivning
`event_id` (i `data`)	UUID	Varningens utlösnings-id — skiljer sig från kuvertets leverans-`event_id`
`rule_id`, `rule_name`	UUID, sträng	Regeln som utlöstes
`metric`	sträng	`success_rate`, `failure_rate`, `avg_score`, `call_volume` eller `suite_regression`
`comparator`	sträng	`lt`, `lte`, `gt` eller `gte`
`metric_value`	tal	Mätvärdets värde under fönstret när regeln utlöstes
`threshold`	tal	Det konfigurerade tröskelvärdet
`window_hours`	heltal	Rullande utvärderingsfönster
`fired_at`	tidsstämpel

Se guiden för varningar för att skapa regler, mätvärden, cooldownperioder och e-post- / Slack-kanaler.

Relaterat

telephony.incoming / web.incoming

Den blockerande nyttolasten för inkommande samtal som du måste svara på.

telephony.complete / web.complete

Transkript och mätvärden efter samtalet.

Webhook-slutpunkter

Prenumerera på en delmängd av dessa händelser med en URL.

Funktionsverktyg

Hur händelserna telephony.tool / web.tool genereras.

Webhooks

Function Tools

Samtalshändelser

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Rösthändelser

`voice.ready`

`voice.failed`

Kvalitetshändelser

`call.graded`

`issue.reported`

Händelser för testsamtal

`test-call.completed`

Varningshändelser

`alert.triggered`

Relaterat

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-slutpunkter

Funktionsverktyg

​Samtalshändelser

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Rösthändelser

​voice.ready

​voice.failed

​Kvalitetshändelser

​call.graded

​issue.reported

​Händelser för testsamtal

​test-call.completed

​Varningshändelser

​alert.triggered

​Relaterat

telephony.incoming / web.incoming

telephony.complete / web.complete

Webhook-slutpunkter

Funktionsverktyg

Samtalshändelser

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Rösthändelser

`voice.ready`

`voice.failed`

Kvalitetshändelser

`call.graded`

`issue.reported`

Händelser för testsamtal

`test-call.completed`

Varningshändelser

`alert.triggered`

Relaterat