Skip to main content
Quando una chiamata telefonica in entrata raggiunge un numero senza un agente assegnato, oppure quando una sessione del widget web si avvia su una chiave pubblicabile in mode="webhook", ThunderPhone invia una richiesta bloccante telephony.incoming / web.incoming al tuo URL webhook legacy e attende fino a 10 secondi una risposta di configurazione. Usa questo scambio per scegliere dinamicamente un prompt, una voce e gli strumenti per ogni chiamata — consulta la guida alla configurazione dinamica delle chiamate per il flusso completo.
Gli endpoint webhook sottoscritti ricevono anch’essi telephony.incoming / web.incoming — per ogni chiamata in entrata e sessione web, con agente configurato o meno — ma queste consegne sono notifiche fire-and-forget con un event_id, mai bloccanti. Solo il webhook legacy a URL singolo gestisce lo scambio di configurazione descritto in questa pagina. I formati delle notifiche degli endpoint sono nel catalogo eventi.
Lo scambio bloccante non dispone di fallback: se il tuo gestore restituisce uno stato non 2xx, supera il timeout o restituisce una configurazione che non supera la convalida, la chiamata viene rifiutata (la chiamata telefonica non si connette; la richiesta della sessione del widget non riesce con 502/422). Rispondi rapidamente — il chiamante sente lo squillo mentre decidi.

Payload della richiesta

Per le chiamate telefoniche (telephony.incoming):
Per le sessioni del widget web (web.incoming), data identifica la pagina di incorporamento anziché i numeri di telefono:
I widget in modalità webhook inviano questa richiesta al valore webhook_url della chiave pubblicabile quando impostato, altrimenti utilizzano l’ URL webhook a livello di organizzazione. In entrambi i casi la richiesta è firmata con il secret webhook dell’organizzazione.

Schema della risposta

Restituisci un oggetto JSON che descrive la configurazione dell’agente per questa chiamata. prompt e voice sono obbligatori; tutto il resto è facoltativo.
Le chiavi di primo livello sconosciute vengono ignorate silenziosamente: un nome di campo con un errore di battitura non rifiuta la configurazione, semplicemente non viene applicato. L’ordine di intervento e max_hold_seconds non sono accettati qui; sono configurabili solo sull’Agente stesso.
Poiché prompt e voice sono obbligatori, restituire {} o qualsiasi risposta che non superi la convalida rifiuta la chiamata con 422 — non esiste un fallback dell’agente statico in questo percorso (un numero o una chiave in modalità webhook non ha un agente assegnato).

Limite delle dimensioni della risposta

Le risposte di configurazione sono limitate a 5 MiB. Se un handler restituisce una risposta più grande, anche con stato 2xx, ThunderPhone segnala che la risposta ha superato il limite e rifiuta la chiamata o la sessione del widget. Limita la risposta ai campi necessari per la configurazione della chiamata; ospita i dati di grandi dimensioni dietro strumenti funzione o un altro servizio invece di incorporarli nella configurazione.

Gestore di esempio


Risposta con strumenti funzione

Collega gli strumenti affinché l’AI possa chiamare le tue API durante la conversazione:
Le richieste agli endpoint degli strumenti sono firmate con lo stesso secret webhook dell’organizzazione che ha firmato questo scambio. Consulta Function Tools per la struttura esatta e il formato della richiesta firmata.

Riepilogo dei livelli di prodotto


Correlati

telephony.complete / web.complete

L’evento di fine chiamata non bloccante.

Strumenti funzione

Schema JSON completo per tools[] e contratto dell’endpoint firmato.

Endpoint webhook

Iscrivi più URL a telephony.incoming / web.incoming.

Configurazione dinamica delle chiamate

Modelli per prompt, strumenti e test A/B per singolo chiamante.