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 o senza agente configurato — 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. Le strutture delle notifiche degli endpoint sono nel
catalogo degli eventi.502/422). Rispondi rapidamente — il chiamante sente lo squillo di attesa 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 proprio
webhook_url della chiave pubblicabile quando impostato, altrimenti usano l’URL
webhook a livello di organizzazione. In entrambi i casi, la richiesta è firmata con il secret
webhook dell’organizzazione.Schema di 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 campo
con nome errato non causa il rifiuto della configurazione, semplicemente non viene applicato. L’ordine di intervento
e
max_hold_seconds non sono accettati qui; sono
configurabili solo sull’agente stesso.prompt e voice sono obbligatori, la restituzione di {} o di qualsiasi
risposta che non superi la convalida causa il rifiuto della chiamata con 422 — non esiste
alcun fallback ad agente statico in questo percorso (un numero o una chiave in modalità webhook
non ha un agente assegnato).
Gestore di esempio
Risposta con strumenti funzione
Allega strumenti affinché l’IA possa chiamare le tue API durante la conversazione:Riepilogo dei livelli 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 ogni chiamante.