Come funziona
- Ti iscrivi all’evento
telephony.incoming(telefono) oweb.incoming(widget). Entrambi sono webhook bloccanti: ThunderPhone attende fino a 10 secondi la tua risposta prima di proseguire la chiamata. - ThunderPhone ti invia
{call_id, from_number, to_number}(le sessioni del widget includono campi specifici del widget anziché numeri — consulta lo schema della richiesta). - Il tuo server risponde con una configurazione dell’agente (prompt, voce, prodotto, strumenti). ThunderPhone usa quella configurazione per la chiamata.
- Se restituisci
{}, si verifica un timeout o un errore, viene usato come fallback l’agente assegnato staticamente. Un’impostazione predefinita sicura.
Funziona allo stesso modo per le chiamate telefoniche (
telephony.incoming) e le
sessioni widget (web.incoming), sia che vengano recapitate a un endpoint webhook
sia al webhook legacy a URL singolo.1. Configura la destinazione del webhook
- Chiamate telefoniche
- Widget web
Per i numeri di telefono, iscrivi il tuo endpoint a La risposta include un
telephony.incoming:secret monouso — salvalo; ti servirà
per la verifica della firma.2. Implementa l’handler
Tre regole pratiche:- Verifica la firma in ogni richiesta (vedi Verifica le firme dei webhook). Non saltare questo passaggio in sviluppo: fallo correttamente una volta e riutilizzalo.
- Rispondi rapidamente. Dieci secondi sono il limite massimo e ogni secondo è silenzio per il chiamante. Esegui ricerche nel database se necessario, ma non chiamare LLM downstream in modo sincrono: se vuoi generare prompt dinamici, precalcolali e memorizzali nella cache.
- Applica un fallback pulito. Qualsiasi stato imprevisto deve restituire
{}affinché l’agente assegnato staticamente gestisca la chiamata.
3. Schema della risposta
Il corpo della risposta corrisponde esattamente allo schema di risposta delle chiamate in entrata. I campi usati più comunemente:L’ordine di parola per chiamata e
max_hold_seconds non sono disponibili nella
risposta del webhook. Impostali sull’
Agente a cui fai riferimento.Pattern
Contesto dell’utente autenticato
Nei widget in modalità webhook, la pagina del visitatore sa già chi è. Chiama il webhook con un parametro di query string che l’SDK del widget inoltra (?customer_id=123) e cerca il cliente lato server.
Rollout del prompt A/B
Prima di implementarlo manualmente, nota che ThunderPhone include una funzionalità nativa di Esperimenti (/dashboard/experiments e la scheda A/B del builder dell’agente) che
definisce varianti, suddivide il traffico e confronta i risultati per variante —
senza webhook.
Se ti serve comunque il controllo lato webhook: calcola l’hash di call_id → bucket;
fornisci il prompt A per 0..49 e il prompt B per 50..99. Registra il
bucket scelto nel tuo DB e in seguito correlalo con la valutazione della chiamata
completata.
Routing basato sull’orario
Orario lavorativo → agente di “supporto dal vivo”; fuori orario → agente per “prendere un messaggio”. Semplice switch sunew Date().getUTCHours() nel tuo handler.
Passaggi successivi
Riferimento del webhook per chiamate in arrivo
Schemi esatti di richiesta e risposta, incluse tutte le chiavi di configurazione.
Verifica le firme dei webhook
Configura correttamente l’HMAC una volta; riutilizzalo ovunque.
Crea un'integrazione di strumenti
Combina il routing dinamico con strumenti per singolo agente.
Semantica di consegna
Riprovi, ordinamento, timeout.