--- title: "Conceptos básicos" description: "Un mapa de todo lo que hay en la plataforma: qué hace cada objeto, dónde se encuentra en el panel y qué API lo utiliza." --- ThunderPhone es una plataforma integral para crear, ejecutar y mejorar agentes de voz con IA. Esta página es el mapa: cada concepto que encontrarás, una sección breve para cada uno, con la interfaz del panel y la API que lo respalda. Revísala una vez y vuelve cuando necesites aclarar algún término. La barra lateral del panel refleja esta estructura: [Agentes](#agents), [voces](#voices), [números de teléfono](#phone-numbers), [widgets web](#web-widgets), [llamadas](#calls), [portales de clientes](#client-portals), [conocimiento](#knowledge-bases). [Monitoreo en vivo](#live-monitoring) y [campañas](#campaigns) salientes. [Aplicaciones, API, servidores MCP y proveedores de VoIP](#connections) que sus agentes pueden usar. [Simulaciones](#simulations), [conjuntos de validación](#validation-sets), [experimentos](#experiments), [problemas](#issues), [informes](#reports), [observabilidad](#observability). [Equipo y roles](#team-and-roles), [claves de API](#organizations), [alertas](#alerts), [facturación](#billing). [Webhooks](#webhooks) y [herramientas de función](#function-tools) para su propio código. --- ## Organizaciones Una **organización** es la unidad de tenencia. Todos los demás recursos — agentes, números de teléfono, llamadas, claves — pertenecen a exactamente una organización. Tu cuenta puede pertenecer a muchas organizaciones; cada una tiene su propio saldo, sus propias claves y su propia lista de miembros. La clave de API `sk_live_` que creas en **Organización → Claves** está vinculada a una organización. Esa vinculación es lo que hace que la API REST sea tan simple: nunca colocas un id de organización en las rutas URL, porque tu clave ya la identifica. **En el panel:** el selector de organización (en el pie de la barra lateral) y la configuración de **Organización** — pestañas para Mi cuenta, General, Claves, Alertas, Configuración de facturación e Historial de facturación. Consulta la [referencia de configuración de la organización](/es/guides/organization-settings). **En la API:** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/developer-api-keys). --- ## Agentes Un **agente** es la configuración de IA que ejecuta una llamada. Incluye: - Un **prompt** que rige lo que dice el agente y cómo se comporta — incluidas acciones de llamada como transferencias, pulsaciones de teclado y colgar, que son líneas simples del prompt en lugar de configuraciones independientes. - Un **nivel de motor** (`spark`, `bolt`, `storm-*`): Spark está optimizado para el costo, Bolt para la velocidad y Storm para la inteligencia en prompts complejos. - Una **voz**, un **idioma principal** y **idiomas adicionales** opcionales — el agente cambia automáticamente cuando quien llama cambia de idioma. Consulta [Idiomas compatibles](/es/guides/supported-languages). - Capacidades adjuntas: [aplicaciones conectadas](#connections), [conexiones de API](#connections), [bases de conocimiento](#knowledge-bases), [servidores MCP](#connections) y [herramientas de función](#function-tools) integradas. - Controles de comportamiento: orden de habla, modo de confirmación, pista de fondo, tiempo de espera en espera. Las ediciones en el creador **se guardan automáticamente en un borrador**; nada se publica hasta que haces clic en **Implementar**. Cada implementación se guarda como una instantánea en la pestaña **Historial** del creador, para que puedas inspeccionar y restaurar cualquier versión anterior. **En el panel:** **Agentes de voz** → el creador de agentes (`/dashboard/agents`). Consulta [Crea tu primer agente de voz](/es/guides/build-an-agent). **En la API:** [`/v1/agents`](/api-reference/agents) — CRUD, duplicar, transferir, historial de versiones y asistentes para prompts. --- ## Voces La **biblioteca de voces** contiene las voces que puede usar un agente, sus muestras reproducibles, idiomas compatibles, agrupaciones por género y acento, y cualquier recargo premium por voz o idioma. Un probador de pago puede sintetizar tu propia frase de 1 a 500 caracteres antes de elegir. Las organizaciones elegibles también pueden crear **voces personalizadas** a partir de una breve muestra WAV o MP3. Las voces personalizadas tienen una cuota y un estado de creación asíncrono; cuando están listas, aparecen en el mismo selector de agentes que las voces de la biblioteca. **En el dashboard:** **Voces** (`/dashboard/voices`). Consulta [Biblioteca de voces y voces personalizadas](/es/guides/voice-library). **En la API:** [`/v1/voices`](/api-reference/voices), [muestras de voz](/api-reference/voice-samples) y [voces personalizadas](/api-reference/custom-voices). --- ## Números de teléfono Un **número de teléfono** pertenece a una organización y enruta las llamadas entrantes a un agente (y puede realizar llamadas salientes). Hay dos fuentes: - **Números de ThunderPhone** — números reales de EE. UU. aprovisionados desde el grupo de ThunderPhone, activos en segundos, {/* rate:phone */}$1/mes más un recargo de 1¢/minuto{/* /rate */}. Inicialmente solo reciben llamadas entrantes. Un administrador de la organización puede solicitar llamadas salientes desde la página **Números de teléfono**; ThunderPhone revisa cada solicitud manualmente, y los números aprobados pueden realizar llamadas y ejecutar campañas. De forma predeterminada, una organización puede tener 25. - **Números de VoIP** — incorporados desde tu propio proveedor mediante una [conexión de VoIP](#connections). Twilio y Telnyx se conectan directamente con una clave de API (Telnyx también ofrece una configuración guiada para cuentas nuevas); SignalWire, Vonage, Plivo y cualquier otro troncal SIP se conectan mediante la configuración SIP, una configuración manual de SIP. Una vez importados y verificados, los números de VoIP admiten llamadas entrantes y salientes. Cada fila de número te permite establecer un modo de enrutamiento, elegir el agente para llamadas entrantes y etiquetar el número. **En el dashboard:** **Números de teléfono** (`/dashboard/phone-numbers`). Consulta [Obtén un número de teléfono](/es/guides/get-a-phone-number). **En la API:** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/phone-number-labels). --- ## Llamadas Cada llamada entrante, llamada saliente, simulación y sesión de widget se convierte en un **registro de llamada**. Una llamada incluye la transcripción completa con etiquetas de roles, el historial estructurado de turnos (incluidas las llamadas a herramientas), una grabación, el total de facturación y calificaciones opcionales de IA e informes de problemas. Mientras una llamada está **en vivo**, puedes abrirla y **escucharla**: te unes en silencio y nadie en la llamada te escucha. Una vez que estás escuchando, puedes **susurrar**: escribe una instrucción que llegue directamente a tu agente durante la llamada; quien llama nunca la escucha y el agente la sigue en tiempo real. **En el dashboard:** **Historial de llamadas** (`/dashboard/call-history`) para el archivo y los detalles de cada llamada; **En vivo** para las llamadas en curso. Consulta [Revisa, escucha y guía tus llamadas](/es/guides/review-calls). **En la API:** [`/v1/calls`](/api-reference/calls) — lista, transcripción, historial, audio, calificación, exportación; [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Portales de clientes Un **portal de cliente** es una vista de historial de llamadas de solo lectura con marca para un cliente externo. Los administradores de la organización eligen los agentes cuyas llamadas aparecen, agregan correos electrónicos de visualizadores aprobados, suben un logotipo y un color de acento, y pueden verificar opcionalmente un dominio personalizado. Los visualizadores del portal pueden revisar detalles de llamadas, transcripciones y grabaciones disponibles sin recibir acceso al dashboard. **En el dashboard:** **Portales de clientes** (`/dashboard/client-portals`). Consulta [Portales de clientes](/es/guides/client-portals). **En la API:** [`/v1/client-portals`](/api-reference/client-portals) para la superficie de administración. ## Widgets web El **widget web** ofrece a quienes visitan tu sitio una conversación basada en micrófono con un agente, sin necesidad de número telefónico. Se autentica con una **clave publicable** (`pk_live_...`) que los navegadores solo pueden usar desde tus dominios permitidos, por lo que es seguro usarla en código del lado del cliente. La lista de dominios no constituye autenticación, y las configuraciones de sesión que una página puede enviar están desactivadas hasta que las permitas en la clave. Las claves funcionan en uno de dos modos: `agent` (vinculada estáticamente a un agente) o `webhook` (tu servidor elige la configuración para cada persona visitante; consulta [Configuración dinámica por llamada](/es/guides/dynamic-call-config)). Las sesiones del widget usan la misma infraestructura de llamadas que las llamadas telefónicas. **En el dashboard:** **Widgets web** (`/dashboard/web-widgets`): crea widgets, configura el modo y el agente, administra los dominios permitidos y copia el fragmento de inserción. Consulta [Crear un widget web](/es/guides/embed-a-web-widget-dashboard). **En la API:** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) y la [documentación del SDK de widgets](/es/widget/overview). --- ## Bases de conocimiento Una **base de conocimiento** es un conjunto de documentos que tu agente puede buscar durante una llamada para fundamentar sus respuestas: carga archivos, pega texto o importa páginas web mediante URL y, luego, vincula la base de conocimiento a un agente en el constructor. El agente la consulta con una herramienta de búsqueda integrada cuando la conversación lo requiere. **En el dashboard:** **Conocimiento** (`/dashboard/knowledge`) para la biblioteca de documentos; la sección **Conocimiento** del constructor para vincular una a un agente. Consulta [Dar a tu agente una base de conocimiento](/es/guides/knowledge-base). --- ## Conexiones Las conexiones permiten que los agentes lleguen al mundo exterior. Cuatro tipos, un grupo en la barra lateral: - **Apps** (`/dashboard/app-connections`): conexiones OAuth con Slack, HubSpot, Salesforce, Google Calendar, Google Sheets y Cal.com. Conéctalas una vez y luego activa herramientas por operación (publicar un mensaje de Slack, actualizar o crear un contacto de HubSpot, reservar un horario en Cal.com…) para cualquier agente. Consulta [Conectar apps](/es/guides/connect-apps). - **APIs** (`/dashboard/api-connections`): convierte cualquier API HTTP en una acción de agente. Pega un comando cURL y el asistente de IA redacta la definición de la herramienta, o créala manualmente; un botón de **Probar solicitud** realiza una llamada de entorno aislado antes de publicar. Consulta [Conexiones de API](/es/guides/api-connections): la interfaz del dashboard de [`/v1/integrations`](/api-reference/integrations). - **MCP** (`/dashboard/mcp-connections`): agrega un servidor de Model Context Protocol mediante URL y permite que el agente use las herramientas que expone. Consulta [Agregar un servidor MCP](/es/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`): credenciales de proveedor para [usar tus propios números telefónicos](#phone-numbers). Consulta [Conectar un proveedor de VoIP](/es/guides/voip-providers). ThunderPhone también expone su propio endpoint MCP para que un cliente MCP externo pueda listar agentes, inspeccionar llamadas y transcripciones, y realizar llamadas. Consulta [Usar ThunderPhone como servidor MCP](/es/guides/thunderphone-mcp-server). **En la API:** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) y [`/v1/voip-connections`](/api-reference/voip-connections); consulta también [Crear una integración de herramientas](/es/guides/build-tool-integration). --- ## Campañas Una **campaña** realiza llamadas salientes a escala: carga un CSV de contactos, elige el agente y el número de origen, y configura la ventana de llamadas (días y horas, según la zona horaria), la simultaneidad y la política de reintentos (intentos máximos y qué resultados —sin respuesta, buzón de voz, fallida— se vuelven a intentar). La campaña recorre la lista y registra cada llamada en el Historial de llamadas. **En el dashboard:** **Campañas** (`/dashboard/campaigns`). Consulta [Ejecutar una campaña de llamadas salientes](/es/guides/outbound-campaigns). **Para llamadas programáticas únicas:** la [API de llamadas salientes](/es/guides/place-outbound-calls). ## Monitoreo en vivo **En vivo** muestra todas las llamadas en curso de la organización y te permite abrir cualquiera de ellas para [escuchar y susurrar](#calls) en tiempo real. Es el área de supervisión: observa cómo un nuevo prompt recibe su primer tráfico real o vigila una campaña en ejecución. **En el dashboard:** **En vivo** (`/dashboard/live`). Consulta [Ver y supervisar llamadas en vivo](/es/guides/monitor-live-calls). --- ## Simulaciones Una **simulación** consiste en que una persona que llama con IA tenga una conversación real con tu agente: misma ruta de telefonía, transcripción real y calificación real, para que puedas hacer pruebas antes (y después) de implementar. Dirígela a un agente o a un número de teléfono, escribe tú mismo el escenario de quien llama o **genera escenarios con IA** a partir del prompt del agente (incluidos casos límite, si los solicitas) y observa la llamada en vivo. Los escenarios se agrupan en **conjuntos** que establecen una tasa mínima de aprobación y pueden condicionar las versiones en CI; las regresiones con respecto a la línea base aceptada se informan por escenario. **En el dashboard:** **Simulaciones** (`/dashboard/simulations`), además del botón **Simulación** dentro del creador de agentes. Consulta [Simular una llamada](/es/guides/simulate-a-call). **En la API:** [`/v1/test-calls`](/api-reference/test-calls) y el ejecutor de conjuntos; consulta [Probar un agente de extremo a extremo](/es/guides/test-agents). --- ## Conjuntos de validación Un **conjunto de validación** convierte momentos reales de llamadas en verificaciones de regresión repetibles de un solo turno. Cada ejemplo conserva el contexto de la conversación, el audio relevante de quien llama, la respuesta original y el comportamiento esperado. Las repeticiones se ejecutan contra el borrador actual del agente sin realizar otra llamada, y el cuadro de diálogo de implementación puede mostrar si la última ejecución sigue coincidiendo con ese borrador. **En el dashboard:** **Conjuntos de validación** (`/dashboard/validation`) para el conjunto de datos de la organización y la pestaña **Validación** del creador de agentes para las ejecuciones. Consulta [Conjuntos de validación](/es/guides/validation-sets). **En la API:** [`/v1/validation-sets`](/api-reference/validation-sets) y los endpoints de repetición de agente/ejemplo en la misma página de referencia. --- ## Experimentos Un **experimento** realiza pruebas A/B de configuraciones de agentes con tráfico en vivo: define variantes (distintos prompts, motores o ajustes), divide el tráfico entre ellas y compara los resultados por variante. Úsalo en lugar de implementar manualmente lógica de segmentación en un webhook. **En el dashboard:** **Experimentos** (`/dashboard/experiments`) y la pestaña **A/B** en el creador de agentes. Consulta [Experimentos (pruebas A/B)](/es/guides/experiments-ab-testing). --- ## Incidencias Una **incidencia** es un problema marcado en una llamada específica, registrado por una persona revisora o detectado por la calificación de IA. Las incidencias incluyen gravedad, origen y estado, y la página Incidencias es la cola de clasificación: filtra, inspecciona la llamada problemática y da seguimiento a las correcciones. **En el dashboard:** **Incidencias** (`/dashboard/issues`), además de la opción de marcar incidencias por llamada en Historial de llamadas. Consulta [Clasificación de incidencias](/es/guides/issues). **En la API:** [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Informes Un **informe** responde una pregunta en lenguaje natural sobre los datos de tus llamadas ("¿Cuáles fueron las tres razones principales por las que quienes llamaron pidieron hablar con una persona la semana pasada?") con un análisis escrito por IA, limitado a los agentes y al intervalo de fechas que elijas. **En el dashboard:** **Informes** (`/dashboard/reports`). Consulta [Informes](/es/guides/reports). --- ## Observabilidad La **observabilidad** es el área de métricas: volumen de llamadas, resultados y calidad a lo largo del tiempo, filtrable por agente e intervalo de tiempo, con exportación para análisis posteriores. **En el dashboard:** **Observabilidad** (`/dashboard/observability`). Consulta [Observabilidad](/es/guides/observability). --- ## Alertas Una **regla de alerta** supervisa una métrica (tasa de éxito, tasa de fallas, puntuación promedio, volumen de llamadas, regresiones de conjuntos) durante un intervalo de tiempo y se activa cuando supera tu umbral. Las notificaciones se envían por correo electrónico y Slack, y activan un evento `alert.triggered` en tus [endpoints de webhook](/es/webhooks/endpoints). **En el dashboard:** **Organización → Alertas**. Consulta [Alertas](/es/guides/alerts). --- ## Webhooks ThunderPhone envía **webhooks HTTP POST** a tu servidor cuando ocurren eventos durante y después de una llamada. Hay dos modelos de entrega: - **Endpoints de webhook** (recomendado): administra varias URL en [`/v1/developer/webhook-endpoints`](/es/webhooks/endpoints) con secretos y suscripciones a eventos por endpoint. - **Webhook heredado de URL única**: una URL por organización. Se administra en [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) o en **Organización → General**. Se mantiene por compatibilidad con versiones anteriores. Los eventos se dividen en dos clases: - Los **eventos bloqueantes** esperan que tu servidor responda con una configuración que define la llamada en curso: los [eventos de llamadas entrantes](/es/webhooks/call-incoming) (`telephony.incoming` / `web.incoming`). Una llamada telefónica espera hasta 13 segundos, incluido un reintento, y una sesión de widget espera 10 segundos. No hay un agente de respaldo: sin una configuración utilizable, la llamada telefónica se finaliza y la sesión de widget falla. - Los **eventos no bloqueantes** son notificaciones de envío único, reintentadas con una espera exponencial; consulta la [semántica de entrega](/es/webhooks/overview). Cada solicitud incluye una firma HMAC-SHA256 con marca de tiempo en `X-ThunderPhone-Signature-V2`, además de la firma heredada basada únicamente en el cuerpo `X-ThunderPhone-Signature`. Consulta la [verificación de firma](/es/webhooks/overview). --- ## Herramientas de función Una **herramienta de función** es un endpoint HTTP al que tu agente puede llamar durante una conversación. Le proporcionas a ThunderPhone un esquema de función al estilo OpenAI junto con una URL de endpoint; el agente decide cuándo llamarlo y ThunderPhone realiza la solicitud HTTP firmada desde sus servidores y entrega el resultado al agente. Los agentes también incluyen **funciones integradas para llamadas**: transferir la llamada, enviar entrada de teclado (DTMF), finalizar la llamada y esperar en espera, que habilitas con líneas simples de prompt en lugar de definiciones de herramientas. **En el dashboard:** la sección **Conexiones de API** del constructor (consulta [Conexiones](#connections)). **En la API:** [`/v1/integrations`](/api-reference/integrations) y la [especificación de herramientas de función](/es/tools/overview). --- ## Equipo y roles Cada organización tiene una lista de miembros con dos roles: los **Miembros** crean y operan agentes; los **Administradores** también administran el equipo y la facturación. Invita por correo electrónico: las invitaciones caducan después de 7 días y pueden revocarse; el menú ⋯ en la fila de un miembro cambia roles o elimina a alguien. El inicio de sesión único puede configurarse para toda la organización; consulta [SSO](/es/guides/sso). **En el dashboard:** **Organización → General**. Consulta [Invita a tu equipo](/es/guides/invite-your-team). **En la API:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/invites). --- ## Facturación ThunderPhone es **prepago**. Cada organización tiene un saldo en USD; las llamadas lo descuentan según la tarifa por minuto del agente (nivel del motor más recargos: el constructor muestra la tarifa total en tiempo real mientras cambias la configuración, y los [idiomas adicionales seleccionados](/es/guides/supported-languages) agregan {/* rate:language */}3¢/min{/* /rate */}). Cuando el saldo llega a cero, las llamadas entrantes se rechazan y las llamadas salientes devuelven `402 Payment Required`. Agrega fondos manualmente o habilita la **recarga automática** con un umbral de saldo, un importe de recarga y un límite de gasto mensual opcional, para que una llamada nunca se corte a mitad de una frase. **En el dashboard:** **Organización → Configuración de facturación** e **Historial de facturación**. Consulta [Agrega fondos y activa la recarga automática](/es/guides/billing-and-topups), además de la [referencia completa de precios](/es/guides/pricing). **En la API:** [`/v1/billing`](/api-reference/billing). --- ## El copiloto integrado El dashboard incluye un **copiloto** integrado: pregúntale "¿cómo hago X?" y responderá a partir de esta documentación, ofrecerá recorridos paso a paso que destacan los controles reales y podrá reproducir cualquiera de los Recorridos guiados. Es la forma más rápida de encontrar un control que esta página menciona. Consulta [Pregunta al copiloto integrado](/es/guides/ask-the-copilot). --- ## Cómo unirlo todo El asistente de cinco pasos: agente → facturación → número → simulación → revisión. La misma primera llamada en cuatro llamadas REST. Crea un agente, agrega fondos, obtén un número, simula y revisa llamadas. Aplicaciones OAuth, API personalizadas, servidores MCP y proveedores de VoIP. Informes, observabilidad, experimentos, incidencias y alertas. Invitaciones y roles, claves de API, seguridad y SSO. Las recetas de la API: entrantes, salientes, configuración dinámica, herramientas y pruebas. Haz correctamente la verificación HMAC una vez y reutilízala en todas partes.