Skip to main content
Per impostazione predefinita, a ogni numero di telefono e chiave pubblicabile è assegnato un agente statico. Quando ti serve una personalizzazione per chiamante o per visitatore — instradamento VIP, contesto dell’utente autenticato, test A/B dei prompt — passa alla modalità webhook e lascia decidere al tuo server.

Come funziona

  1. Ti iscrivi all’evento telephony.incoming (telefono) o web.incoming (widget). Entrambi sono webhook bloccanti: ThunderPhone attende fino a 10 secondi la tua risposta prima di proseguire la chiamata.
  2. 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).
  3. Il tuo server risponde con una configurazione dell’agente (prompt, voce, prodotto, strumenti). ThunderPhone usa quella configurazione per la chiamata.
  4. 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

Per i numeri di telefono, iscrivi il tuo endpoint a telephony.incoming:
La risposta include un 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 su new 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.