> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Configurazione dinamica per chiamata > Scegli un agente — o riscrivi un prompt — per ogni chiamata in arrivo in base a una logica personalizzata in un webhook. 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`](/it/webhooks/events) (telefono) o [`web.incoming`](/it/webhooks/events) (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](/it/webhooks/call-incoming)). 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`: ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Prod call-incoming", "url": "https://example.com/thunderphone/incoming", "events": ["telephony.incoming"] }' ``` La risposta include un `secret` monouso — salvalo; ti servirà per la verifica della firma. Per le sessioni widget, crea una chiave pubblicabile in `mode="webhook"` con l'URL dell'endpoint incluso: ```bash theme={null} curl -X POST https://api.thunderphone.com/v1/publishable-key \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Dynamic widget", "mode": "webhook", "webhook_url": "https://example.com/thunderphone/widget-incoming", "allowed_domains": ["example.com"] }' ``` Il widget effettuerà una richiesta POST a questo URL all'avvio di ogni sessione. ## 2. Implementa l'handler Tre regole pratiche: * **Verifica la firma** in ogni richiesta (vedi [Verifica le firme dei webhook](/it/guides/verify-webhook-signatures)). 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. ```python FastAPI theme={null} import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, sig: str) -> bool: expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, sig or "") @app.post("/thunderphone/incoming") async def incoming(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(401) event = json.loads(body) if event["type"] not in ("telephony.incoming", "web.incoming"): return {} # fall back to default caller = event["data"]["from_number"] # Cheap DB lookup: is this a known VIP? customer = lookup_customer(caller) if customer and customer.tier == "vip": return { "prompt": f"You are a VIP concierge for {customer.name}. Be proactive…", "voice": "john", "product": "storm-base", } return {} # default agent handles non-VIPs def lookup_customer(phone: str): # ... your CRM integration ... pass ``` ```javascript Express theme={null} import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, sig) { const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); return sig && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)); } app.post( "/thunderphone/incoming", express.raw({ type: "application/json" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); const IMPORTANT_TYPES = new Set([ "telephony.incoming", "web.incoming", ]); if (!IMPORTANT_TYPES.has(event.type)) return res.json({}); const customer = await lookupCustomer(event.data.from_number); if (customer?.tier === "vip") { return res.json({ prompt: `You are a VIP concierge for ${customer.name}. Be proactive…`, voice: "john", product: "storm-base", }); } res.json({}); // fall back to default agent }, ); ``` ## 3. Schema della risposta Il corpo della risposta corrisponde esattamente allo [schema di risposta delle chiamate in entrata](/it/webhooks/call-incoming). I campi usati più comunemente: | Campo | Tipo | Descrizione | | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------- | | `prompt` | stringa (obbligatorio) | Prompt di sistema per l'agente | | `voice` | stringa (obbligatorio) | ID voce da [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | stringa | Il valore predefinito è `spark` | | `background_track` | stringa \| null | ID dell'audio ambientale | | `acknowledgement_prompt_mode` | stringa | `auto` o `manual` (solo Storm-with-ack) | | `acknowledgement_prompt` | stringa | Obbligatorio quando la modalità è `manual` | | `tools` | array | Schemi inline degli strumenti funzione: vedi [Strumenti funzione](/it/tools/overview) | L'ordine di parola per chiamata e `max_hold_seconds` non sono disponibili nella risposta del webhook. Impostali sull' [Agente](/api-reference/agents) 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](/it/guides/concepts) (`/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 Schemi esatti di richiesta e risposta, incluse tutte le chiavi di configurazione. Configura correttamente l'HMAC una volta; riutilizzalo ovunque. Combina il routing dinamico con strumenti per singolo agente. Riprovi, ordinamento, timeout.