> ## 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. # Configuración dinámica por llamada > Elige un agente — o reescribe un prompt — para cada llamada entrante según una lógica personalizada en un webhook. De forma predeterminada, cada número de teléfono y clave publicable tiene asignado un agente estático. Cuando necesites personalización **por quien llama** o **por visitante** — enrutamiento VIP, contexto de usuarios con sesión iniciada, pruebas A/B de prompts — cambia al modo webhook y deja que tu servidor decida. ## Cómo funciona 1. Suscríbete al evento [`telephony.incoming`](/es/webhooks/events) (teléfono) o [`web.incoming`](/es/webhooks/events) (widget). Ambos son webhooks **bloqueantes**: ThunderPhone espera hasta 10 segundos tu respuesta antes de continuar la llamada. 2. ThunderPhone te envía `{call_id, from_number, to_number}` (las sesiones del widget incluyen campos específicos del widget en lugar de números; consulta el [esquema de solicitud](/es/webhooks/call-incoming)). 3. Tu servidor responde con una configuración de agente (prompt, voz, producto, herramientas). ThunderPhone usa esa configuración para la llamada. 4. Si devuelves `{}`, se agota el tiempo de espera o ocurre un error, se usa como alternativa el agente asignado estáticamente. Una opción predeterminada segura. Funciona de forma idéntica para llamadas telefónicas (`telephony.incoming`) y sesiones del widget (`web.incoming`), ya sea que se entreguen a un endpoint de webhook o al webhook heredado de una sola URL. ## 1. Configura el destino del webhook Para números de teléfono, suscribe tu 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 respuesta incluye un `secret` de un solo uso; guárdalo, lo usarás para verificar la firma. Para sesiones del widget, crea una clave publicable en `mode="webhook"` con la URL de tu endpoint incorporada: ```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"] }' ``` El widget enviará un POST a esta URL al inicio de cada sesión. ## 2. Implementa el controlador Tres reglas generales: * **Verifica la firma** en cada solicitud (consulta [Verificar firmas de webhooks](/es/guides/verify-webhook-signatures)). No omitas esto en desarrollo; hazlo bien una vez y reutilízalo. * **Responde rápido**. Diez segundos es el límite estricto, y cada segundo es silencio para quien llama. Haz consultas a la base de datos si lo necesitas, pero no llames LLM posteriores de forma síncrona; si quieres generar prompts dinámicos, precalcúlalos y almacénalos en caché. * **Usa una alternativa limpia**. Cualquier estado inesperado debe devolver `{}` para que el agente asignado estáticamente gestione la llamada. ```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. Esquema de respuesta El cuerpo de la respuesta coincide exactamente con el [esquema de respuesta de llamadas entrantes](/es/webhooks/call-incoming). Los campos más usados: | Campo | Tipo | Descripción | | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- | | `prompt` | cadena (obligatorio) | Prompt del sistema para el agente | | `voice` | cadena (obligatorio) | ID de voz de [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | cadena | El valor predeterminado es `spark` | | `background_track` | cadena \| null | ID de audio ambiental | | `acknowledgement_prompt_mode` | cadena | `auto` o `manual` (solo Storm con confirmación) | | `acknowledgement_prompt` | cadena | Obligatorio cuando el modo es `manual` | | `tools` | arreglo | Esquemas de herramientas de función en línea; consulta [Herramientas de función](/es/tools/overview) | El orden de habla por llamada y `max_hold_seconds` no están disponibles en la respuesta del webhook. Configúralos en el [Agente](/api-reference/agents) al que haces referencia. ## Patrones ### Contexto de usuario con sesión iniciada En los widgets en modo webhook, la página del visitante ya sabe quién es. Llama a tu webhook con un parámetro de cadena de consulta que el SDK del widget reenvía (`?customer_id=123`) y busca al cliente del lado del servidor. ### Lanzamiento de prompts A/B Antes de implementar esto manualmente, ten en cuenta que ThunderPhone cuenta con una función nativa de [Experimentos](/es/guides/concepts) (`/dashboard/experiments` y la pestaña **A/B** del generador de agentes) que define variantes, divide el tráfico y compara los resultados por variante, sin necesidad de webhook. Si de todos modos necesitas control desde el webhook: aplica hash a `call_id` → grupo; usa el prompt A para `0..49` y el prompt B para `50..99`. Registra el grupo que elegiste en tu propia base de datos y luego correlaciónalo con la calificación de la llamada completada. ### Enrutamiento según la hora Horario comercial → agente de "soporte en vivo"; fuera de horario → agente de "tomar un mensaje". Cambio simple según `new Date().getUTCHours()` en tu controlador. *** ## Próximos pasos Esquemas exactos de solicitud y respuesta, incluida cada clave de configuración. Configura correctamente el HMAC una vez; reutilízalo en todas partes. Combina el enrutamiento dinámico con herramientas por agente. Reintentos, orden, tiempos de espera.