Webhooks

Catalogo degli eventi

Tutti i tipi di eventi webhook emessi da ThunderPhone.

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 tutto — tranne gli eventi per turno telephony.turn / web.turn, che vengono inviati solo agli endpoint che li specificano esplicitamente).

Questi eventi vengono trasmessi con due modalità:

• Le consegne agli endpoint sono sempre notifiche non bloccanti con ritentativi: rispondi con qualsiasi 2xx; l'involucro include 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' instradamento degli strumenti in modalità webhook. La tua risposta definisce la chiamata in tempo reale.

Gli esempi di payload seguenti mostrano l'involucro dell'endpoint nel suo ordine di trasmissione (chiavi ordinate alfabeticamente: data, event_id, type); le consegne legacy contengono 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 all'endpoint sono notifiche fire-and-forget inviate per ogni chiamata in entrata, sia che il numero sia configurato per un agente o per 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, l'URL della registrazione quando disponibile 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 strumenti integrati, della base di conoscenza, di connessione 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 eseguito: {"status": <http status>, "response": <your endpoint's JSON>} in caso di successo, oppure {"status": <status>, "error": "<message>"} in caso di errore.

telephony.turn#

Inviato durante una chiamata telefonica in corso, una volta per ogni turno contenente parlato man mano che avviene — le risposte vocali dell'agente e i turni trascritti del chiamante. Ti consente di seguire la conversazione in tempo reale tramite webhook standard anziché effettuare polling su GET /v1/calls/{call_id}/transcript. Non bloccante.

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

L'equivalente sul canale web di telephony.incoming, inviato quando una sessione del widget web o una chiamata di test del microfono del builder inizia. Le consegne all'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 del builder, origin_domain e publishable_key_prefix sono vuoti.

web.complete#

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

web.tool#

L'equivalente sul canale web di telephony.tool. Il campo data contiene origin_domain invece di from_number / to_number.

web.turn#

L'equivalente sul canale web di telephony.turn, che copre le chiamate del widget web e le chiamate di test del microfono del builder. Stessa struttura del payload, con origin_domain invece di from_number / to_number. Come telephony.turn, richiede una sottoscrizione esplicita — non viene mai consegnato tramite un array events vuoto.

Eventi vocali#

La creazione di voci personalizzate è asincrona. Questi eventi non bloccanti consentono di reagire a un risultato finale anziché eseguire il polling dell' endpoint dei dettagli del clone.

voice.ready#

Inviato quando una voce personalizzata termina l'elaborazione e può essere assegnata a un agente.

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

Inviato quando l'elaborazione di una voce personalizzata raggiunge un errore permanente.

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

Eventi di qualità#

call.graded#

Inviato ogni volta che una 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"
}

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

Eventi delle chiamate di test#

test-call.completed#

Inviato quando una 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"
}

Eventi di avviso#

alert.triggered#

Inviato quando una regola di avviso con il canale Invia ai webhook degli sviluppatori abilitato supera la propria soglia. Non bloccante. Una regola si attiva una volta e poi rispetta il proprio 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"
}

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

Correlati#