Configuración de Twilio (Voz y Números de Teléfono)

Conecta Twilio a Helios para voz y números de teléfono: guarda credenciales una vez, vincula un número y Helios configura los webhooks.

Objetivo

Conecta Twilio a Helios para que tus agentes de IA puedan atender llamadas telefónicas. Guardas tu Account SID y Auth Token de Twilio una sola vez en Integrations; Helios los reutiliza para números de voz y grabación de llamadas. Si prefieres no gestionar una cuenta de Twilio, Helios puede aprovisionarte un número directamente (ver Números aprovisionados por Helios).

Twilio se usa solo para voz y números de teléfono. WhatsApp ya no se conecta a través de Twilio: los números de WhatsApp se conectan exclusivamente a través de Meta con el botón Connect with WhatsApp. Ver WhatsApp y WhatsApp con Meta Cloud API.

Acceso

Sidebar -> Integrations; Ruta: /app/{tenant}/integrations (tarjeta Twilio (Voice), en la categoría Communication)
Sidebar -> Voice Agents; Ruta: /app/{tenant}/voice-agents (Create Voice Agent -> paso del teléfono)
Sidebar -> Phone Numbers; Ruta: /app/{tenant}/phone-numbers (comprar un número de Helios)

Roles

Área	Quién puede usarla
Guardar o desconectar credenciales de Twilio (Integrations)	Solo Owner y Admin, con el email verificado.
Crear / editar Voice Agents	Cualquier miembro del equipo. La voz debe estar incluida en tu plan o añadida como add-on de Voice.
Comprar, renombrar o liberar números de Helios	Solo Owner y Admin. Comprar también requiere el email verificado.

Requisitos previos

Solo si traes tu propio número: una cuenta de Twilio activa con acceso a la Twilio Console, tu Account SID (empieza con AC, 34 caracteres) y tu Auth Token (32 caracteres), y un número de Twilio con capacidad de voz. Nada de esto es necesario para un número de Helios.
Voz incluida en tu plan, o el add-on de Voice.
Un email verificado en tu cuenta de Helios.

Dos formas de conseguir un número de voz

Helios admite dos modelos. Puedes combinarlos.

Modelo	Qué haces	Ideal para
Traer tu propio Twilio	Guardas tus credenciales de Twilio y vinculas un número existente de Twilio a un voice agent. Helios configura los webhooks del número por ti.	Equipos que ya usan Twilio.
Número aprovisionado por Helios	Compras un número dentro de Helios. Sin cuenta de Twilio, sin webhooks y con grabación incluida.	Voice agents que solo necesitan un número funcional rápido.

Paso 1 - Guarda tus credenciales de Twilio

Hazlo una sola vez. Las mismas credenciales se reutilizan en todo lo que necesita Twilio. Solo los owners y admins pueden guardarlas o desconectarlas.

Abre /app/{tenant}/integrations y busca la tarjeta Twilio (Voice) (búscala por nombre o usa el filtro Communication). Haz clic en la tarjeta para abrirla.
Para encontrar tus credenciales: inicia sesión en console.twilio.com, abre el panel Account Info del dashboard y copia el Account SID y el Auth Token.
Pega ambos valores en el formulario. Cada campo se valida mientras escribes y te indica cuando el valor parece correcto.
Haz clic en Save Twilio Credentials.

Campo	Regla
Twilio Account SID	Debe empezar con `AC` y tener exactamente 34 caracteres.
Twilio Auth Token	Debe tener exactamente 32 caracteres.

Helios guarda ambos valores cifrados. El Auth Token (no una API Key) es obligatorio porque Helios lo usa para verificar que las solicitudes de webhook entrantes provienen realmente de Twilio. Para desconectar más adelante, abre la misma tarjeta y haz clic en Disconnect Twilio.

Integración de Twilio

Paso 2 - Conecta un número para Voz

Abre /app/{tenant}/voice-agents e inicia Create Voice Agent.
En el paso del teléfono, elige cómo conectar un número. La elección aparece cuando tienes al menos un número de Helios; si no, el paso va directo al flujo de Twilio y enlaza a Phone Numbers para que compres un número de Helios en minutos.

Opción	Descripción
Helios number (Recommended)	Usa un número que compraste a través de Helios. Totalmente gestionado, webhooks configurados automáticamente, nada que configurar.
Your own Twilio number	Conecta una cuenta de Twilio y apunta un número existente de Twilio a Helios.

Para Your own Twilio number: guarda Twilio en la tarjeta Twilio Integration (si aún no está conectado) y luego usa Select an existing Twilio number para elegir uno de tu cuenta (Refresh numbers recarga la lista), o elige Enter manually y escribe el número en formato E.164 (por ejemplo +15551234567).
Con tus credenciales de Twilio guardadas, Helios configura los webhooks de voz del número en Twilio automáticamente al guardar el voice agent. El modal sigue mostrando el Voice Webhook URL y el Status Callback URL con botones de copiar, para que verifiques los valores en Twilio o los configures a mano.

Configuración del webhook en Twilio (verificación / configuración manual)

Ve a Twilio Console > Active Numbers.
Selecciona el número que estás conectando.
En la sección Voice Configuration, los valores deben ser:

Ajuste	Valor
A call comes in	Webhook -> el Voice Webhook URL (termina en `/api/voice/webhook`).
HTTP method	HTTP POST.
Call status changes	El Status Callback URL (termina en `/api/voice/status-callback`).
Status callback method	HTTP POST.

Después de eso, las llamadas entrantes al número se enrutan a tu voice agent automáticamente. Si los webhooks se desincronizan (por ejemplo, tras cambios hechos directamente en Twilio), usa el botón Repair connection en la tarjeta del voice agent para resincronizarlos.

Grabación de llamadas

Activa Call Recording en el paso de comportamiento del voice agent para guardar las grabaciones y revisarlas después.

Número de Helios: la grabación está incluida. No se necesitan credenciales de Twilio.
Tu propio número de Twilio: la grabación requiere una conexión activa de Twilio. Si Twilio aún no está conectado, el interruptor de grabación muestra un formulario de credenciales (Connect Twilio).
Las grabaciones aparecen en la página de detalle de cada llamada y se conservan 90 días.
Helios guarda el audio por su cuenta y elimina la copia de tu cuenta de Twilio una vez almacenado, así que las grabaciones no acumulan cargos de almacenamiento en Twilio.

Números aprovisionados por Helios (sin cuenta de Twilio)

Si no quieres gestionar Twilio tú mismo, compra un número directamente a través de Helios y asígnalo a un voice agent. Solo los owners y admins pueden gestionar números de teléfono.

Abre /app/{tenant}/phone-numbers.
Haz clic en Buy a number. El asistente tiene cuatro pasos: Choose a number, Emergency address, Confirm purchase, Number purchased.
Busca por Area code y/o Contains (ambos opcionales) y haz clic en Search. Hoy solo hay números de EE. UU. disponibles; los códigos de área fuera de EE. UU. (como +1 809) no devuelven resultados.
Introduce la Emergency address. La ley de EE. UU. exige una dirección registrada para llamadas de emergencia (911); se usa solo para el envío de emergencias y nunca se comparte con quienes llaman.

Campo	Notas
Business or full name	A nombre de quién se registra la dirección.
Street address	Solo calle y unidad. Ciudad, estado y ZIP van en sus propios campos.
City / State / ZIP code	El estado se elige de una lista; el ZIP tiene 5 dígitos.
Name for this number	Referencia opcional (por defecto "Helios number"). Puedes cambiarla después.

Revisa el precio mensual que muestra el paso de confirmación, acepta los Phone Number Terms and Acceptable Use Policy y haz clic en Purchase.
Asigna el nuevo número a un voice agent (Assign it to a voice agent en el paso de éxito).

Gestión de tus números:

La lista muestra cuántos números usas del máximo de tu plan, el estado de cada número (Active / Released), la fecha de compra y si la dirección de emergencia está registrada.
Edit name renombra un número. El nombre lo identifica en toda la app — en voice agents y al conectar WhatsApp.
Un número de Helios también puede usarse para conectar WhatsApp; ver WhatsApp.
Libera un número cuando ya no lo necesites. La liberación es inmediata y no se puede deshacer; tendrías que comprar un número nuevo para reemplazarlo. Un número conectado a WhatsApp no se puede liberar — desconéctalo primero en la sección de WhatsApp.

Notas:

Buscar es gratis en todos los planes. Comprar requiere un cupo disponible del límite de tu plan más cualquier add-on de Phone Number; sin cupo, el paso de confirmación muestra un enlace View plans en lugar del botón de compra.
Los números son solo para IA de voz entrante. Sin spam ni robocalls.
Si más adelante tu plan incluye menos números de los que tienes, los conservas todos pero no puedes comprar más hasta liberar algunos o mejorar el plan.
Si la página muestra "Phone numbers are not available yet", la función no está habilitada en tu entorno. Se está desplegando de forma gradual; contacta a soporte si la necesitas.

URLs de webhook (referencia)

Los webhooks se configuran automáticamente: al comprar en el caso de números de Helios, y al guardar un voice agent en el caso de tus propios números de Twilio (con credenciales guardadas). Para verificación o configuración manual, los sufijos de ruta son:

Propósito	Sufijo de ruta	Método
Llamada de voz entrante	`/api/voice/webhook`	POST
Status callback de voz	`/api/voice/status-callback`	POST

Buenas prácticas

Guarda Twilio una sola vez en Integrations; todos los flujos de voz lo reutilizan.
Usa los botones Copy para los URLs de webhook en lugar de escribirlos a mano.
Mantén el Account SID y el Auth Token correctos. Si rotas el Auth Token en Twilio, actualízalo en Helios o las verificaciones de firma de webhook empezarán a fallar.
Prefiere un número de Helios si quieres cero configuración y grabación incluida.
Si cambias la configuración de un número directamente en Twilio, usa después Repair connection en la tarjeta del voice agent.
Prueba con una llamada real después de conectar un número.

Errores comunes

Problema	Causa probable / solución
"Invalid Account SID"	El SID debe empezar con `AC` y tener 34 caracteres.
"Invalid Auth Token"	El token debe tener 32 caracteres. Pégalo de nuevo desde la Twilio Console.
No se pueden guardar las credenciales	No eres owner ni admin, o tu email no está verificado.
No aparecen números al conectar	Las credenciales no coinciden con una cuenta de Twilio con números, o el número no está en Twilio. Revisa las credenciales o introduce el número manualmente.
No llegan las llamadas	Los webhooks del número faltan o son incorrectos. Haz clic en Repair connection en la tarjeta del voice agent, o verifica los URLs en Twilio.
Faltan las grabaciones	Para tu propio número de Twilio, Twilio debe estar conectado y el Status Callback URL configurado como `/api/voice/status-callback` con HTTP POST.
"Voice is not included in your current plan"	Mejora tu plan o añade el add-on de Voice para configurar voice agents.
"Phone numbers are not available yet"	La función de números aprovisionados por Helios se está desplegando de forma gradual; contacta a soporte.
"This number is connected to WhatsApp"	Desconecta el número primero en la sección de WhatsApp y luego libéralo en Phone Numbers.