Conceptos básicos

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:

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.

En la API: /v1/orgs, /v1/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.
• Capacidades adjuntas: aplicaciones conectadas, conexiones de API, bases de conocimiento, servidores MCP y herramientas de función 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.

En la API: /v1/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.

En la API: /v1/voices, muestras de voz y voces personalizadas.

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, $1/mes más un recargo de 1¢/minuto. 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. 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.

En la API: /v1/phone-numbers, /v1/voip-connections, /v1/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.

En la API: /v1/calls — lista, transcripción, historial, audio, calificación, exportación; /v1/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.

En la API: /v1/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). 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.

En la API: /v1/publishable-key, /v1/mic-session y la documentación del SDK de widgets.

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.

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.
• 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: la interfaz del dashboard de /v1/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.
• VoIP (/dashboard/voip-connections): credenciales de proveedor para usar tus propios números telefónicos. Consulta Conectar un proveedor de VoIP.

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.

En la API: /v1/integrations, /v1/mcp-servers y /v1/voip-connections; consulta también Crear una integración de herramientas.

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.

Para llamadas programáticas únicas: la API de llamadas salientes.

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 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.

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.

En la API: /v1/test-calls y el ejecutor de conjuntos; consulta Probar un agente de extremo a extremo.

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.

En la API: /v1/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).

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.

En la API: /v1/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.

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.

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.

En el dashboard: Organización → Alertas. Consulta Alertas.

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 con secretos y suscripciones a eventos por endpoint.
• Webhook heredado de URL única: una URL por organización. Se administra en /v1/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 (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.

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.

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).

En la API: /v1/integrations y la especificación de herramientas de función.

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.

En el dashboard: Organización → General. Consulta Invita a tu equipo.

En la API: /v1/members, /v1/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 agregan 3¢/min). 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, además de la referencia completa de precios.

En la API: /v1/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.

Cómo unirlo todo#