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.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.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
Gestore di esempio
Risposta con strumenti funzione
Collega gli strumenti affinché l’AI possa chiamare le tue API durante la conversazione: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.
