Skip to main content
Quando una chiamata telefonica in entrata raggiunge un numero senza un agente assegnato, oppure quando una sessione del widget web viene avviata 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 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.
Lo scambio bloccante non prevede fallback: se il tuo handler restituisce uno stato non 2xx, va in timeout o restituisce una configurazione che non supera la convalida, la chiamata viene rifiutata (la chiamata telefonica non viene connessa; la richiesta della sessione del widget non riesce con 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.
Poiché 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:
Le richieste agli endpoint degli strumenti sono firmate con lo stesso segreto webhook dell’organizzazione che ha firmato questo scambio. Consulta Strumenti funzione per la struttura esatta e il formato delle richieste firmate.

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.