Getting Started

Conceptos fundamentales

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. Cada otro recurso — agentes, números de teléfono, llamadas, claves — pertenece exactamente a 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. Esta vinculación es lo que hace que la API REST sea tan simple: nunca incluyes un ID de organización en las rutas de 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 define lo que dice el agente y cómo se comporta — incluidas acciones de llamada como transferencias, pulsaciones de teclas 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 junto con un idioma principal y idiomas adicionales opcionales — el agente cambia automáticamente cuando quien llama cambia de idioma. Consulta Idiomas compatibles.
• Capacidades adjuntas: apps conectadas, conexiones de API, bases de conocimiento, servidores MCP y herramientas de función en línea.
• Controles de comportamiento: orden de habla, modo de confirmación, pista de fondo, tiempo de espera en espera.

Las ediciones en el generador 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 generador, para que puedas inspeccionar y restaurar cualquier versión anterior.

En el panel: Agentes de voz → el generador de agentes (/dashboard/agents). Consulta Crea tu primer agente de voz.

En la API: /v1/agents — CRUD, duplicar, transferir, historial de versiones y asistentes de prompt.

Voces#

La biblioteca de voces contiene las voces que un agente puede usar, sus muestras reproducibles, idiomas compatibles, agrupaciones por género y acento, y cualquier recargo por voz o idioma premium. Un muestreador de pago puede sintetizar tu propia frase de 1 a 500 caracteres antes de que elijas.

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 panel: 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 demostración — números reales de EE. UU. aprovisionados desde el grupo de ThunderPhone, activos en segundos. Solo para llamadas entrantes, responden con un breve aviso hablado y el panel limita cada organización a 10 de ellos. Ideales para una primera prueba; no para producción.
• Números de VoIP — se incorporan desde tu propio proveedor mediante una conexión VoIP. Twilio y Telnyx se conectan directamente (Telnyx tiene una configuración guiada); SignalWire y Vonage estarán disponibles próximamente; actualmente puedes acceder a ellos mediante configuración manual de SIP, que acepta cualquier troncal SIP. Una vez importados y verificados, los números VoIP admiten llamadas entrantes y salientes.

Cada fila de número te permite configurar un modo de enrutamiento, elegir el agente para llamadas entrantes y etiquetar el número.

En el panel: 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 llamadas. Una llamada incluye la transcripción completa etiquetada por rol, 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 vivo.

En el panel: 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 orienta 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 clientes 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, cargan un logotipo y un color de acento y, de forma opcional, verifican un dominio personalizado. Los visualizadores del portal pueden inspeccionar detalles de llamadas, transcripciones y grabaciones disponibles sin recibir acceso al panel.

En el panel: Portales de clientes (/dashboard/client-portals). Consulta Portales de clientes.

En la API: /v1/client-portals para la interfaz de administración.

Widgets web#

El widget web ofrece a quienes visitan tu sitio una conversación por micrófono con un agente, sin necesidad de número telefónico. Se autentica con una clave publicable (pk_live_...) vinculada al origen de tus dominios permitidos, por lo que es segura para usar en código del cliente.

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 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 Crea 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 builder. 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 builder para vincular una a un agente. Consulta Proporciona una base de conocimiento a tu agente.

Conexiones#

Las conexiones permiten que los agentes lleguen al mundo exterior. Cuatro tipos, un grupo en la barra lateral:

• Aplicaciones (/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 (enviar un mensaje de Slack, crear o actualizar un contacto de HubSpot, reservar un horario en Cal.com…) para cualquier agente. Consulta Conecta aplicaciones.
• APIs (/dashboard/api-connections): convierte cualquier API HTTP en una acción del agente. Pega un comando cURL y el asistente de IA redactará 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 Agrega un servidor MCP.
• VoIP (/dashboard/voip-connections): credenciales de proveedor para usar tus propios números telefónicos. Consulta Conecta 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 Usa ThunderPhone como servidor MCP.

En la API: /v1/integrations, /v1/mcp-servers y /v1/voip-connections; consulta también Crea 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, con zona horaria), la concurrencia y la política de reintentos (máximo de intentos y qué resultados — sin respuesta, buzón de voz, fallida — se reintentan). La campaña avanza por la lista y registra cada llamada en el Historial de llamadas.

En el dashboard: Campañas (/dashboard/campaigns). Consulta Ejecuta una campaña de llamadas salientes.

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

Monitoreo en vivo#

En vivo muestra cada llamada en curso de la organización y te permite abrir cualquiera para escuchar y susurrar en tiempo real. Es la superficie de supervisión: observa cómo un prompt nuevo 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 es una persona que llama con IA y mantiene una conversación real con tu agente — misma ruta de telefonía, transcripción real, evaluación real — para que puedas realizar pruebas antes (y después) de lanzar. Asígnala a un agente o a un número telefónico, escribe tú mismo el escenario de quien llama o genera escenarios con IA a partir del prompt del agente (incluidos los casos extremos, si los solicitas) y observa la llamada en vivo.

Los escenarios se agrupan en conjuntos que fijan una tasa mínima de aprobación y pueden bloquear lanzamientos en CI; las regresiones respecto de 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 de llamadas reales 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 reproducciones se ejecutan con el borrador actual del agente sin realizar otra llamada, y el cuadro de diálogo de implementación puede mostrar si la ejecución más reciente todavía coincide 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 reproducció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 configuraciones), divide el tráfico entre ellas y compara los resultados por variante. Úsalo en lugar de implementar manualmente lógica de asignación a grupos 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 un revisor humano o detectado por la evaluación con 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 realiza seguimiento de las correcciones.

En el dashboard: Incidencias (/dashboard/issues), además del marcado por llamada en el Historial de llamadas. Consulta Clasificación de incidencias.

En la API: /v1/issue-reports.

Informes#

Un informe responde una pregunta en lenguaje natural sobre tus datos de llamadas ("¿Cuáles fueron las tres principales razones por las que quienes llamaban pidieron hablar con una persona la semana pasada?") con un análisis redactado por IA, limitado a los agentes y al rango de fechas que elijas.

En el dashboard: Informes (/dashboard/reports). Consulta Informes.

Observabilidad#

La observabilidad es la sección de métricas: volumen de llamadas, resultados y calidad a lo largo del tiempo, filtrable por agente y ventana 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 una ventana de tiempo y se activa cuando supera tu umbral. Las notificaciones se envían por correo electrónico y Slack, y generan un evento alert.triggered para 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. Dos modelos de entrega:

• Endpoints de webhook (recomendado): administra muchas URL en /v1/developer/webhook-endpoints con secretos por endpoint y suscripciones a eventos por endpoint.
• Webhook heredado de una sola URL: 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 llamada entrante (telephony.incoming / web.incoming). Tienes hasta 10 segundos para responder; si se agota el tiempo, el agente asignado estáticamente atiende la llamada.
• Los eventos no bloqueantes son notificaciones de envío único, reintentadas con espera exponencial; consulta la semántica de entrega.

Cada solicitud incluye una firma HMAC-SHA256 en 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 capacidades integradas para llamadas: transferir la llamada, enviar entrada de teclado (DTMF), finalizar la llamada, esperar en espera, que habilitas con líneas simples en el prompt en lugar de definiciones de herramientas.

En el dashboard: la sección Conexiones de API del creador (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 vencen 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 creador 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 monto 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 en la aplicación#

El dashboard incluye un copiloto integrado: pregúntale "cómo hago X" y responderá según 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 en la aplicación.

Integrarlo todo#