Configuración de Twilio (WhatsApp + Voz)
Conecta Twilio a Helios para WhatsApp y voz: guarda las credenciales una vez y vincula números y webhooks.
Objetivo
Conecta Twilio a Helios para que tus agentes de IA puedan enviar y recibir mensajes de WhatsApp y atender llamadas telefónicas. Guardas tu Account SID y Auth Token de Twilio una sola vez en Integrations; Helios los reutiliza tanto para números de WhatsApp como para llamadas de voz. Si prefieres no gestionar una cuenta de Twilio, Helios puede aprovisionarte un número directamente (ver Números aprovisionados por Helios).
Acceso
- Sidebar -> Integrations; Ruta: /app/{tenant}/integrations (tarjeta Twilio)
- Sidebar -> WhatsApp; Ruta: /app/{tenant}/whatsapp (Connect New Number -> Twilio)
- Sidebar -> Voice Agents; Ruta: /app/{tenant}/voice-agents (Create Voice Agent -> número de teléfono)
- Sidebar -> Phone Numbers; Ruta: /app/{tenant}/phone-numbers (comprar un número de Helios)
Roles
| Área | Quién puede usarla |
|---|---|
| Guardar credenciales de Twilio (Integrations) | Cualquier miembro del equipo con el email verificado. Las cuentas con email sin verificar no pueden guardar credenciales. |
| Conectar un número de WhatsApp | Owner, Admin o Agent |
| Crear / editar Voice Agents | Tu equipo, según tu acceso a voice agents |
| Comprar o liberar números de Helios | Solo Owner y Admin |
Requisitos previos
- Una cuenta de Twilio activa con acceso a la Twilio Console.
- Tu Account SID de Twilio (empieza con
AC, 34 caracteres) y tu Auth Token (32 caracteres). - Para WhatsApp: un número de Twilio ya registrado como WhatsApp Sender.
- Para voz: un número de Twilio con capacidad de voz, o un número comprado a través de Helios.
- Un email verificado en tu cuenta de Helios.
Dos formas de usar Twilio
Helios admite dos modelos. Puedes combinarlos.
| Modelo | Qué haces | Ideal para |
|---|---|---|
| Traer tu propio Twilio | Guardas tus credenciales de Twilio y apuntas los webhooks de tus números de Twilio a Helios. | Equipos que ya usan Twilio, o que necesitan WhatsApp en Twilio. |
| Número aprovisionado por Helios | Compras un número dentro de Helios. Sin cuenta de Twilio ni webhooks que configurar. | 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 para WhatsApp y voz.
- Abre /app/{tenant}/integrations y busca la tarjeta Twilio (Voice & WhatsApp).
- 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 la tarjeta.
- 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.
Paso 2 - Conecta un número de WhatsApp (Twilio)
- Abre /app/{tenant}/whatsapp y haz clic en Connect New Number.
- Elige el proveedor Twilio (la alternativa es Meta Cloud API; ver WhatsApp con Meta Cloud API).
- Si Twilio aún no está conectado, introduce tu Account SID y Auth Token y haz clic en Connect Twilio Account. Esto guarda las mismas credenciales del Paso 1.
- Define un Display Name y elige el agente (o equipo) que responderá.
- En WhatsApp Phone Number, selecciona un número habilitado para WhatsApp de tu cuenta de Twilio, o elige Enter number manually y escríbelo como
whatsapp:+[country code][phone number]. - Copia el Webhook URL que muestra el modal y configúralo en Twilio (a continuación).
Configura el webhook de WhatsApp en Twilio
El modal muestra el Webhook URL exacto que debes usar (termina en /api/whatsapp/webhook). Cópialo con el botón y luego, en Twilio:
- Ve a Twilio Console > WhatsApp Senders.
- Selecciona tu número habilitado para WhatsApp.
- En Endpoint Configuration, define:
| Ajuste | Valor |
|---|---|
| Webhook URL for incoming messages | Pega el URL del modal. |
| Status callback URL | Pega el mismo URL. |
| Fallback URL | Déjalo vacío. |
| Method | HTTP POST en ambos. |
Si aún no tienes un WhatsApp Sender, sigue la guía de WhatsApp para registrar un número en Twilio y vincularlo a tu WhatsApp Business Account.
Paso 3 - 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:
| 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 (si aún no está conectado) y luego selecciona un número de tu cuenta de Twilio o introdúcelo manualmente en formato E.164 (por ejemplo
+15551234567). - Copia el Voice Webhook URL y el Status Callback URL que muestra el modal y configúralos en Twilio (a continuación).
Configura el webhook de voz en Twilio
- Ve a Twilio Console > Active Numbers.
- Selecciona el número que estás conectando.
- En la sección Voice Configuration, define:
| Ajuste | Valor |
|---|---|
| A call comes in | Webhook -> pega el Voice Webhook URL (termina en /api/voice/webhook). |
| HTTP method | HTTP POST. |
| Call status changes | Pega el Status Callback URL (termina en /api/voice/status-callback). |
| Status callback method | HTTP POST. |
Tras guardar en Twilio, las llamadas entrantes a ese número se enrutan a tu voice agent automáticamente. Si en su lugar usas un número de Helios, la telefonía y los webhooks se gestionan por ti y no hay nada que configurar.
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.
- Abre /app/{tenant}/phone-numbers.
- Haz clic en Buy a number.
- Busca por Area code y/o Contains (ambos opcionales). Hoy solo hay números de EE. UU. disponibles.
- Introduce una 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.
- Revisa el costo mensual, acepta los Phone Number Terms and Acceptable Use Policy y confirma la compra.
- Asigna el nuevo número a un voice agent.
Notas:
- Buscar es gratis en todos los planes. Comprar requiere un plan de pago; si tu plan no otorga cupos de compra, el asistente muestra un enlace de mejora en lugar de un botón de compra.
- Los números son solo para IA de voz entrante. Sin spam ni robocalls.
- Libera un número desde la lista 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.
- 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 el flujo de compra 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)
Copia siempre el URL exacto desde el modal correspondiente de Helios (usa tu dominio de producción). Los sufijos de ruta son:
| Propósito | Sufijo de ruta | Método |
|---|---|---|
| WhatsApp entrante + estado | /api/whatsapp/webhook | POST |
| 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; WhatsApp y 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 para voz si quieres cero configuración de webhooks.
- Prueba con un mensaje o llamada real después de configurar el webhook.
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 | Tu email no está verificado. Verifícalo y vuelve a intentarlo. |
| 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 mensajes ni llamadas | Falta el webhook URL en Twilio o es incorrecto, o está en un método distinto a HTTP POST. Vuelve a copiar el URL del modal. |
| Faltan el estado de voz o las grabaciones | El Status Callback URL no está configurado como /api/voice/status-callback con HTTP POST. |
| "Phone numbers are not available yet" | La función de números aprovisionados por Helios se está desplegando de forma gradual; contacta a soporte. |