Catalogo eventi

Ogni corpo del webhook ha un campo type il cui valore è uno dei tipi di evento in questa pagina. Quando ti iscrivi a un endpoint, l’array events deve contenere i tipi di evento desiderati (oppure essere vuoto per iscriverti a tutti). Questi eventi vengono inviati in due modalità:

Le consegne agli endpoint sono sempre notifiche non bloccanti con ritenti: rispondi con qualsiasi 2xx; l’involucro contiene un event_id per la deduplicazione.
Gli scambi bloccanti vengono eseguiti solo sul webhook legacy a URL singolo: la richiesta di configurazione telephony.incoming / web.incoming (numeri in modalità webhook e chiavi widget, timeout di 10 s) e l’invio di strumenti in modalità webhook. La tua risposta modella la chiamata in corso.

Gli esempi di payload seguenti mostrano l’involucro dell’endpoint nell’ordine di trasmissione (chiavi ordinate alfabeticamente: data, event_id, type); le consegne legacy includono gli stessi data senza event_id.

Eventi di chiamata

`telephony.incoming`

Inviato quando una chiamata in entrata raggiunge uno dei tuoi numeri di telefono. Le consegne agli endpoint sono notifiche fire-and-forget inviate per ogni chiamata in entrata, indipendentemente dal fatto che il numero sia configurato con un agente o con un webhook. I numeri senza un agente assegnato ricevono inoltre la richiesta di configurazione bloccante sul webhook legacy — consulta telephony.incoming / web.incoming per lo schema completo di richiesta / risposta.

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

`telephony.complete`

Inviato al termine di una chiamata telefonica in entrata o in uscita. Non bloccante. Include la trascrizione completa, l’URL della registrazione e il riepilogo della fatturazione. Consulta telephony.complete / web.complete per lo schema del payload.

`telephony.tool`

Inviato dopo che una chiamata telefonica richiama uno strumento funzione. Notifica di audit non bloccante — lo strumento è già stato eseguito quando questo evento viene consegnato; riguarda i tuoi strumenti funzione (non gli strumenti integrati, della knowledge base, delle connessioni app o MCP).

{
  "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 è il risultato dell’esecuzione: {"status": <http status>, "response": <your endpoint's JSON>} in caso di successo oppure {"status": <status>, "error": "<message>"} in caso di errore.

`web.incoming`

L’equivalente del canale web di telephony.incoming, inviato quando inizia una sessione di widget web o una chiamata di test del microfono nel builder. Le consegne agli endpoint sono fire-and-forget per ogni sessione web. Le chiavi pubblicabili in mode="webhook" ricevono inoltre la richiesta di configurazione bloccante sul webhook legacy — tale richiesta bloccante ha una struttura diversa (origin_domain, publishable_key_prefix; nessun numero di telefono). Consulta 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 è sempre il valore letterale "web". Per le sessioni del widget in modalità webhook, to_number è vuoto (il numero dell’agente della sessione viene assegnato dopo la configurazione); per le chiamate di test del microfono nel builder, origin_domain e publishable_key_prefix sono vuoti.

`web.complete`

L’equivalente del canale web di telephony.complete, che copre le chiamate del widget web (direction: "web") e le chiamate di test del microfono nel builder (direction: "test"). Non bloccante. Stessa struttura del payload di telephony.complete, più origin_domain, con from_number impostato su "web".

Sul webhook legacy con URL singolo, le chiamate di test del microfono nel builder vengono storicamente segnalate come telephony.complete — solo le chiamate con direction: "web" utilizzano qui il tipo web.complete. Il sistema degli endpoint mappa sia le chiamate web sia quelle di test su web.*. I payload storici possono contenere i valori legacy di direction widget o mic.

`web.tool`

L’equivalente del canale web di telephony.tool. data contiene origin_domain anziché from_number / to_number.

Eventi di qualità

`call.graded`

Inviato ogni volta che un’esecuzione di valutazione AI viene completata per una chiamata. Non bloccante.

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

Campo	Tipo	Descrizione
`grade.id`	integer	ID della valutazione
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` o `no_conversation`
`grade.summary`	string	Riepilogo di un paragrafo
`grade.detected_issues`	array	Stringhe dei problemi rilevati dal valutatore
`grade.status`	string	Sempre `completed` — vengono emessi solo gli eventi delle esecuzioni completate
`grade.grader_model`	string	Il valutatore che ha prodotto il risultato (ad es. `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Una chiamata può essere valutata più di una volta — una valutazione euristica rapida è spesso seguita da una valutazione completa del modello una volta che la registrazione è disponibile, e sono possibili rivalutazioni manuali. Ogni esecuzione completata emette il proprio evento call.graded; considera autorevole il valore graded_at più recente.

`issue.reported`

Inviato quando viene creata una segnalazione di problema — inviata da un utente dalla dashboard (source: "user") oppure automaticamente dalla valutazione della chiamata (source: "system"). Non bloccante.

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

Campo	Tipo	Descrizione
`issue_report.severity`	string	`critical`, `warning` o `info`
`issue_report.status`	string	`open` o `resolved`
`issue_report.source`	string	`user` (inviata dalla dashboard) o `system` (creata dalla valutazione)

Rivalutare una chiamata ricrea le relative segnalazioni di problema generate dal sistema, emettendo nuovamente issue.reported per le segnalazioni ricreate. Esegui la deduplicazione in base a call_id + title se vuoi ricevere una sola notifica per ogni problema sottostante.

Eventi delle chiamate di test

`test-call.completed`

Inviato quando un’esecuzione di chiamata di test raggiunge uno stato terminale — completed o failed, incluse le esecuzioni che non sono riuscite all’avvio e non hanno mai prodotto una chiamata. Non bloccante. Utile per collegare esecuzioni CI batch ai sistemi di chat/notifiche.

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

Campo	Tipo	Descrizione
`test_call_run.target_type`	string	`agent` o `phone_number`
`test_call_run.target_id`	integer	L’ID dell’agente o del numero di telefono a cui era destinata l’esecuzione, corrispondente a `target_type`
`test_call_run.status`	string	`completed` o `failed`
`test_call_run.call_id`	integer \| null	`null` quando l’esecuzione non riesce prima dell’avvio di una chiamata
`test_call_run.error_message`	string	Vuoto in caso di successo

Eventi di avviso

`alert.triggered`

Inviato quando una regola di avviso con il canale Invia ai webhook per sviluppatori abilitato supera la propria soglia. Non bloccante. Una regola scatta una sola volta e poi rispetta il proprio periodo di cooldown, quindi una violazione persistente produce un evento per ogni finestra di cooldown.

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

Campo	Tipo	Descrizione
`event_id` (in `data`)	UUID	L’ID di attivazione dell’avviso, distinto dall’`event_id` di consegna dell’envelope
`rule_id`, `rule_name`	UUID, string	La regola che è scattata
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume` o `suite_regression`
`comparator`	string	`lt`, `lte`, `gt` o `gte`
`metric_value`	number	Il valore della metrica nella finestra quando la regola è scattata
`threshold`	number	La soglia configurata
`window_hours`	integer	Finestra di valutazione retrospettiva
`fired_at`	timestamp

Consulta la guida agli avvisi per creare regole, metriche, periodi di cooldown e canali email / Slack.

Correlati

telephony.incoming / web.incoming

Il payload bloccante della chiamata in entrata a cui devi rispondere.

telephony.complete / web.complete

Trascrizione e metriche post-chiamata.

Endpoint webhook

Sottoscrivi un URL a un sottoinsieme di questi eventi.

Strumenti funzione

Come vengono generati gli eventi telephony.tool / web.tool.

Webhooks

Function Tools

Eventi di chiamata

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventi di qualità

`call.graded`

`issue.reported`

Eventi delle chiamate di test

`test-call.completed`

Eventi di avviso

`alert.triggered`

Correlati

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoint webhook

Strumenti funzione

​Eventi di chiamata

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Eventi di qualità

​call.graded

​issue.reported

​Eventi delle chiamate di test

​test-call.completed

​Eventi di avviso

​alert.triggered

​Correlati

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoint webhook

Strumenti funzione

Eventi di chiamata

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Eventi di qualità

`call.graded`

`issue.reported`

Eventi delle chiamate di test

`test-call.completed`

Eventi di avviso

`alert.triggered`

Correlati