Händelsekatalog

Varje webhook-payload har ett type-fält vars värde är en av händelsetyperna på den här sidan. När du prenumererar på en endpoint måste events-arrayen innehålla de händelsetyper du vill ha (eller vara tom för att prenumerera på allt). Två leveransstilar skickar dessa händelser:

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

Exempel-payloadarna nedan visar endpoint-omslaget 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. Endpointleveranser är skicka-och-glöm-meddelanden som skickas för varje inkommande samtal, oavsett om numret är agentkonfigurerat eller webhook-konfigurerat. 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 telefonisamtal avslutas. Icke-blockerande. Innehåller hela transkriberingen, inspelnings-URL och faktureringssammanfattning. Se telephony.complete / web.complete för payloadschemat.

`telephony.tool`

Skickas efter att ett telefonisamtal anropar ett funktionsverktyg. Icke-blockerande granskningsnotis — verktyget har redan körts när händelsen levereras; det omfattar dina egna funktionsverktyg (inte inbyggda verktyg, kunskapsbasverktyg, appanslutningsverktyg 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 resultatet av körningen: {"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 webbwidget-session eller ett mikrofontestsamtal i byggaren startar. Endpointleveranser är skicka-och-glöm-meddelanden 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 ett annat format (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 ordagranna värdet "web". För widgetsessioner i webhook-läge är to_number tomt (sessionens agentnummer tilldelas efter konfiguration); för mikrofontestsamtal i byggaren är origin_domain och publishable_key_prefix tomma.

`web.complete`

Webbkanalens motsvarighet till telephony.complete, som omfattar samtal via webbwidgeten (direction: "web") och mikrofontestsamtal i byggaren (direction: "test"). Icke-blockerande. Samma payloadformat 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. Endpointsystemet mappar både webb- och testsamtal till web.*. Historiska payloads 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.

Kvalitetshändelser

`call.graded`

Skickas när en AI-bedömning 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…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

Fält	Typ	Beskrivning
`grade.id`	integer	Bedömnings-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 hittats av bedömaren
`grade.status`	string	Alltid `completed` — endast slutförda körningar skickas
`grade.grader_model`	string	Vilken bedömningsmodell som skapade resultatet (t.ex. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Ett samtal kan bedömas fler än en gång — en snabb heuristisk bedömning följs ofta av en fullständig modellbedömning när inspelningen är tillgänglig, och manuella ombedömningar ä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 samtalsbedömning (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"
}

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 genom bedömning)

Att ombedöma ett samtal bygger om dess systemgenererade problemrapporter, vilket skickar issue.reported på nytt för de återskapade rapporterna. Deduplicera på call_id + title om du bara vill ha en avisering per underliggande problem.

Händelser för testsamtal

`test-call.completed`

Skickas när en körning av testsamtal når en slutlig status — 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"
}

Fält	Typ	Beskrivning
`test_call_run.target_type`	string	`agent` eller `phone_number`
`test_call_run.target_id`	integer	Agent-id eller telefonnummer-id 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. Icke-blockerande. En regel utlöses en gång och följer sedan sin cooldown, så en ihållande överträdelse genererar en händelse per cooldown-fö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 omslagets `event_id` för leverans
`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`	nummer	Mätvärdets värde under fönstret när regeln utlöstes
`threshold`	nummer	Det konfigurerade tröskelvärdet
`window_hours`	heltal	Löpande utvärderingsfönster
`fired_at`	tidsstämpel

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

Relaterat

telephony.incoming / web.incoming

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

telephony.complete / web.complete

Transkription och mätvärden efter samtalet.

Webhook-slutpunkter

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

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`

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

​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`

Kvalitetshändelser

`call.graded`

`issue.reported`

Händelser för testsamtal

`test-call.completed`

Varningshändelser

`alert.triggered`

Relaterat