Manual de referencia: Twilio

Datos de esta lección
Fase	MAN — Manuales de referencia
Módulo	MAN — Biblioteca de consulta

Objetivo práctico

Este manual reúne, en un único documento de consulta, la compra de números (DID), la configuración de voz y SIP, el modelo real de facturación y control de gasto de Twilio (incluida la pregunta de si existe o no un «hard limit» vinculante), la seguridad de sus credenciales, la accesibilidad de su consola con NVDA, y el catálogo de códigos de error de telefonía más relevantes para un agente de IA, con su diagnóstico. Úsalo como referencia puntual, no como lectura lineal.

Resultado que obtendrás

Un documento de consulta permanente al que volver mientras trabajas con Twilio: desde la primera compra de un número hasta el diagnóstico de un código de error concreto en una llamada real meses después.

Dónde encaja dentro del sistema final

Dentro del sistema TELÉFONO → AGENTE → CEREBRO → VOZ → AUTOMATIZACIÓN → CALENDARIO, Twilio es el proveedor de referencia de este curso para la pieza TELÉFONO: la compañía que proporciona la línea física y el número real conectado a la red telefónica pública, y que dirige cada llamada entrante hacia el AGENTE (Vapi o Retell) mediante configuración de voz o de un troncal SIP. Sin esta pieza, el resto del sistema puede funcionar en pruebas por navegador, pero nunca recibirá una llamada real de un cliente.

Conocimientos previos

Haber completado el módulo 2.4 (numeración, SIP/VoIP y configuración de un número con Twilio) dentro de la progresión del curso.
Límites de gasto (módulo 2.1), en concreto el funcionamiento verificado del saldo prepago de Twilio.
Protocolo de creación segura de cuentas y de gestión de credenciales del módulo 2.1.

Herramientas necesarias

Una cuenta de Twilio creada siguiendo el protocolo de seguridad del módulo 2.1.
Un navegador con NVDA activo.
Documentación de identidad y domicilio del negocio, por si el país y tipo de número exigen un Regulatory Bundle.

Posible coste

Modelo de precios (verificado el 30 de agosto de 2026): Twilio funciona por pago por uso («Pay-as-you-go»), sin cuota de plataforma mensual, sin licencias por puesto y sin gasto mínimo obligatorio en cuentas de autoservicio. Se paga por lo que efectivamente se consume: minutos de llamada (entrante y saliente, con tarifas distintas según el país de origen y destino), mensajes SMS, y el alquiler mensual recurrente de cada número comprado. Las cifras concretas por país y tipo de número cambian con cierta frecuencia y deben consultarse siempre en la página oficial de precios (twilio.com/en-us/pricing) en el momento de presupuestar, no memorizarse de una consulta anterior.

Compra de un número: además del coste por minuto de las llamadas, comprar un número implica un coste mensual recurrente propio, variable según país y tipo (local, móvil, gratuito).

Saldo prepago: según el centro de ayuda oficial de Twilio, las cuentas de pago por uso funcionan con un saldo prepago: se recarga saldo por adelantado y el consumo se descuenta de ese saldo. Twilio notifica por correo cuando el saldo llega a 5 USD y de nuevo cuando llega a 0 USD; si el saldo llega a 0 sin recarga automática activada, el proyecto se suspende y deja de poder cursar llamadas o mensajes hasta que se recargue saldo manualmente.

Advertencia de seguridad

Sobre el «hard limit» de gasto — ampliación de lo verificado en el módulo 2.1: Twilio no expone, según la documentación oficial consultada, un único control de «límite de gasto máximo» de un solo clic dentro de la consola que detenga automáticamente el servicio al llegar a una cifra elegida por ti. Lo que sí existe, verificado directamente contra la documentación oficial:

El saldo prepago sin recarga automática actúa, en la práctica, como límite vinculante: al llegar a 0 USD, el proyecto se suspende. Este es el mecanismo principal y más fiable de control de gasto en una cuenta de autoservicio.
Los Usage Triggers («disparadores de uso») permiten configurar un webhook que se activa al superar un umbral de consumo que tú defines (por ejemplo, más de 30 USD de gasto en un día, o llamadas de duración anormalmente larga). Según el propio centro de ayuda de Twilio, este mecanismo puede usarse, como parte de una estrategia antifraude, para disparar una acción automatizada —incluida la suspensión de una subcuenta— en respuesta a ese webhook. Es importante ser preciso aquí: el Usage Trigger por sí solo solo envía una notificación; la suspensión efectiva de la (sub)cuenta al recibir esa notificación es una acción que debes implementar tú mismo (por ejemplo, mediante una llamada a la API de Twilio para suspender la subcuenta) y no ocurre de forma automática por el simple hecho de configurar el trigger.
Una cuenta puede ser suspendida automáticamente por Twilio si el saldo se vuelve negativo o hay pagos vencidos, o por motivos de fraude detectado por el propio Twilio; estas suspensiones no son configurables por ti como un tope de gasto, son reacciones del propio sistema de Twilio.

Algunas fuentes no oficiales (blogs y agregadores de terceros) mencionan la existencia de un campo de «límite de gasto» configurable directamente en la consola de Twilio como un tope duro de autoservicio. Información no confirmada con suficiente fiabilidad en la documentación oficial consultada: no se ha podido verificar contra una fuente oficial de Twilio (documentación, centro de ayuda o changelog) la existencia de ese control como una función de autoservicio de un solo clic, distinta del saldo prepago y de los Usage Triggers ya descritos. No des por hecho que existe hasta comprobarlo tú mismo dentro de tu propia consola en el momento de leer este manual.

Protección de credenciales: según la documentación oficial de seguridad de Twilio, usar el Account SID y el Auth Token principales como credenciales de autenticación es razonable en pruebas locales, pero arriesgado en producción: si alguien obtiene esas dos credenciales, compromete la cuenta completa. La alternativa recomendada son las API Keys, credenciales generadas específicamente para autenticación, gestionables de forma independiente (creación, revocación) sin afectar a la cuenta principal. Se pueden crear API Keys individuales por propósito o por persona/subsistema, y se pueden restringir mediante Restricted API Keys a un conjunto mínimo de permisos necesarios. Si una API Key se compromete, basta con borrarla y crear una nueva, sin necesidad de rotar el Auth Token principal. Nunca incluyas credenciales en código fuente ni en texto plano: usa variables de entorno. Para validar la firma de Webhooks entrantes desde Twilio, se usa específicamente el Auth Token, no una API Key.

Modelo mental

Piensa en Twilio como en la compañía telefónica que te alquila la línea física y el número: no decide qué se dice durante la llamada (eso es el AGENTE y el CEREBRO), ni cómo suena la voz (eso es la VOZ); su responsabilidad es que la llamada llegue, con la calidad y la cobertura regulatoria de un operador de telecomunicaciones real, y que puedas dirigirla hacia el sistema que hayas construido.

Explicación

Según la documentación oficial de Twilio verificada el 30 de agosto de 2026, la compra de un número se realiza desde la consola, en «Numbers and Senders» (dentro de «Products & services»), con la opción «Set up a new phone number», o por la ruta equivalente «Develop → Phone Numbers → Manage → Buy a Number». Puedes filtrar por país, capacidades (voz, SMS, MMS) y, en opciones avanzadas, por tipo de número (local, móvil, gratuito) y zona de cobertura. Para un agente telefónico, la capacidad imprescindible es Voice.

Regulatory Bundle: numerosos países —incluida España, sujeta al Código Europeo de Comunicaciones Electrónicas y a la normativa española de numeración— exigen, antes de activar un número local, un paquete regulatorio de documentos de identidad y, a menudo, de domicilio. Twilio lo solicita automáticamente dentro del propio proceso de compra cuando el país y tipo de número lo requieren.

Configuración de voz de un número: una vez comprado, un número se conecta con un agente de dos formas principales. La primera, más simple, es configurar directamente en la ficha del número una «Webhook URL» de voz que Twilio invocará con una petición HTTP cada vez que llegue una llamada, devolviendo la plataforma de destino (Vapi o Retell) el TwiML o la instrucción necesaria para conectar la llamada. La segunda, más avanzada, es el SIP Trunking (Elastic SIP Trunking): un troncal SIP configurado en «Voice → SIP Trunks» que enruta la señalización de la llamada hacia un sistema externo compatible con SIP, en lugar de hacia un simple Webhook HTTP. La configuración de un troncal SIP en Twilio implica cuatro componentes: creación del troncal (con un nombre identificable), configuración de credenciales (una lista de credenciales con usuario y contraseña segura, exigida con mayúsculas, minúsculas, números y símbolos), configuración de control de acceso (listas de control de acceso por IP, para restringir qué direcciones pueden originar tráfico hacia el troncal en producción) y, finalmente, asociación del número de teléfono al troncal SIP creado, en la sección «Voice» de la ficha del número.

Región del troncal SIP: si vas a operar en una región concreta (por ejemplo, Europa), el troncal SIP debe crearse como recurso dentro de esa región antes de poder usarse en ella; un troncal creado en la región por defecto no se traslada automáticamente a otra región.

Vocabulario nuevo

DID (Direct Inward Dialing)

Piénsalo así: El número de línea directa de una extensión concreta dentro de una centralita telefónica más grande.

Número de teléfono real, conectado a la red telefónica pública, que puede recibir llamadas entrantes directamente y dirigirlas a un sistema concreto. Es el término técnico habitual para lo que Twilio llama simplemente «número de teléfono».

Ejemplo: Un DID español (+34) comprado en Twilio para la recepción telefónica de un negocio.

Regulatory Bundle

Piénsalo así: La documentación de identidad y domicilio que pide una operadora antes de dar de alta una línea a nombre de tu negocio.

Conjunto de documentos exigidos por la normativa de un país concreto para activar un número de teléfono, gestionado dentro del propio proceso de compra de Twilio.

Ejemplo: Un número local español puede requerir un Regulatory Bundle con documentación de identidad antes de quedar activo.

SIP Trunk (troncal SIP)

Piénsalo así: Una línea troncal dedicada entre dos centralitas, en lugar de una llamada individual como cualquier otra.

Conexión de señalización de voz mediante el protocolo SIP entre Twilio y un sistema externo, usada como alternativa avanzada al enrutamiento por Webhook HTTP simple.

Ejemplo: Un troncal SIP que conecta un número de Twilio directamente con una plataforma de terceros compatible con SIP.

Usage Trigger

Piénsalo así: Una alarma que suena al superar un consumo concreto, sin cortar por sí misma el suministro.

Mecanismo de Twilio que envía un webhook a una URL configurada cuando se supera un umbral de uso definido por ti (por ejemplo, gasto diario). No suspende la cuenta por sí solo: la suspensión, si se desea, debe implementarse como una acción propia en respuesta al webhook.

Ejemplo: Un Usage Trigger a 30 USD de gasto diario que, mediante tu propio código, llama a la API de Twilio para suspender la subcuenta.

API Key (Twilio)

Piénsalo así: Una llave adicional del despacho, distinta de la llave maestra del edificio (el Account SID + Auth Token), que se puede anular sin cambiar la cerradura principal.

Credencial de autenticación generada de forma independiente al Account SID y al Auth Token principales, revocable sin comprometer el resto de la cuenta, y que puede restringirse a un conjunto mínimo de permisos (Restricted API Key).

Ejemplo: Una API Key restringida usada exclusivamente por el backend de un cliente concreto, revocable sin afectar a otros proyectos.

Preparación

Ten tu cuenta de Twilio iniciada, a mano tu documentación de identidad y domicilio del negocio por si el país exige un Regulatory Bundle, y decide de antemano si vas a enrutar la voz por Webhook HTTP simple (más sencillo, suficiente para la mayoría de proyectos de este curso) o por SIP Trunking (necesario solo si la plataforma de destino lo exige explícitamente).

Procedimiento paso a paso

Contexto: Vas a generar una API Key restringida para un proyecto concreto, en lugar de usar el Account SID y el Auth Token principales.
Acción de teclado: Inicia sesión en la consola de Twilio. Recorre encabezados con H hasta «Account → API keys & tokens», o busca «API Keys» desde el buscador interno de la consola. Activa «Create API key» con Enter.
Respuesta esperada de NVDA: NVDA debería anunciar un texto similar a «Create API key, botón», y tras activarlo, un formulario con nombre, tipo de clave (estándar o restringida) y, si eliges restringida, los permisos concretos a habilitar.
Qué significa: Elegir «Restricted» te permite limitar la clave al mínimo necesario (por ejemplo, solo Voice), reduciendo el daño posible si la clave llegara a filtrarse.
Acción siguiente: Copia el Secret mostrado a tu gestor de contraseñas de inmediato: como en la mayoría de plataformas, no volverá a mostrarse completo tras cerrar este cuadro.
Contexto: Vas a configurar el enrutamiento de voz de un número ya comprado hacia tu agente, mediante Webhook HTTP.
Acción de teclado: Recorre encabezados con H hasta «Numbers and Senders → Active Numbers», localiza el número con Tab o con la navegación por tablas de NVDA, y ábrelo con Enter. Dentro de la ficha, localiza la sección «Voice Configuration» y el campo «A call comes in».
Respuesta esperada de NVDA: NVDA debería anunciar el selector de tipo de configuración (Webhook, TwiML Bin, SIP Trunk, entre otros) y, si eliges Webhook, un campo de texto para la URL.
Qué significa: La URL configurada aquí es exactamente la que Vapi o Retell te proporcionan al conectar un número externo desde su propio panel.
Acción siguiente: Pega la URL proporcionada por Vapi o Retell, guarda los cambios, y realiza una llamada de prueba real al número para confirmar el enrutamiento.
Contexto: Vas a crear un troncal SIP como alternativa avanzada al Webhook, si tu plataforma de destino lo requiere.
Acción de teclado: Recorre encabezados con H hasta «Voice → SIP Trunking» (Elastic SIP Trunking). Activa «Create new Trunk» con Enter y asígnale un nombre identificable. Después, recorre las secciones «Credential Lists» y «IP Access Control Lists» para configurar autenticación y restricción de acceso.
Respuesta esperada de NVDA: NVDA anunciará cada sección del troncal (Origination, Termination, Credential Lists, ACLs) conforme la recorras con encabezados.
Qué significa: Un troncal sin restricción de IP configurada acepta tráfico desde cualquier origen que conozca las credenciales: en producción, restringe siempre el acceso a las IP conocidas de tu plataforma de destino.
Acción siguiente: Asocia el número de teléfono a este troncal desde la sección «Voice» de su ficha, sustituyendo la configuración de Webhook si la tenía.

Posibles diferencias de interfaz

Twilio ha renovado su consola («Numbers and Senders») en 2026, sustituyendo progresivamente rutas anteriores. Si no encuentras exactamente los nombres indicados, busca por el concepto («Buy a Number», «API Keys», «SIP Trunking») desde el buscador interno de la consola, o consulta la documentación oficial enlazada en «Fuentes».

Problema de accesibilidad y alternativa

Según la documentación oficial de Twilio, la compañía declara conformidad progresiva con WCAG 2.1 nivel AA y con la Section 508 para sus productos, y su sistema de diseño interno (Twilio Paste, usado en partes de la consola y en Twilio Flex) se prueba explícitamente con lectores de pantalla, incluido NVDA. En la práctica, este curso ha comprobado que la consola estándar de gestión de números, API Keys y SIP Trunking descrita en este manual es navegable con NVDA mediante encabezados, tablas y formularios estándar, sin necesidad de alternativas.

Puntos de atención: algunas áreas de la consola incorporan paneles de estadísticas y gráficos de uso (por ejemplo, en «Monitor → Insights») que pueden no ofrecer una alternativa textual completa a la información visual del gráfico. Si te encuentras con un panel de este tipo cuya información no se anuncia de forma útil con NVDA, la alternativa más fiable es consultar el mismo dato mediante la API de uso de Twilio (Usage Records API), que devuelve las mismas cifras en un formato estructurado, en lugar de depender de la interpretación visual del gráfico.

Errores frecuentes y diagnóstico

Código de error 11200 — HTTP retrieval failure.

Cómo localizarlo: Según el diccionario oficial de errores de Twilio, significa que Twilio no pudo obtener una respuesta correcta de la URL configurada (por ejemplo, la Webhook URL de voz de tu número): tu servidor devolvió un código de estado 4xx o 5xx, hubo una interrupción de red entre Twilio y tu servidor, o un cortafuegos/WAF bloqueó la petición entrante de Twilio. Para llamadas de voz, Twilio espera una respuesta durante aproximadamente 15 segundos, incluyendo el tiempo de conexión TCP y el establecimiento TLS.

Solución: Revisa los logs de tu servidor o de la plataforma (Vapi/Retell) para el momento exacto de la llamada, confirma que la URL configurada en Twilio responde con un código 2xx, y revisa cualquier cortafuegos que pudiera estar bloqueando peticiones desde los rangos de IP de Twilio.

Código de error 13224 — Dial: Twilio does not support calling this number or the number is invalid.

Cómo localizarlo: El número de destino especificado en una instrucción de marcado (Dial) no es válido o no está soportado por Twilio en el formato en que se ha enviado.

Solución: Revisa el formato del número (formato E.164, con prefijo internacional, por ejemplo +34 para España) en la configuración o en el código que genera la llamada saliente.

Código de error 21211 — problema de capacidad del número.

Cómo localizarlo: El número usado en la petición no tiene habilitada la capacidad necesaria (por ejemplo, voz) para la operación solicitada.

Solución: Verifica, en la ficha del número dentro de «Numbers and Senders», que la capacidad «Voice» está efectivamente activa; si no lo está, ese número no sirve para este curso y debe sustituirse por uno que sí la tenga.

El proyecto deja de poder cursar llamadas o mensajes sin aviso aparente.

Cómo localizarlo: Lo más probable es que el saldo prepago haya llegado a 0 USD sin recarga automática activada, lo que suspende el proyecto según el funcionamiento documentado del sistema de facturación de Twilio; también puede deberse a una suspensión por saldo negativo, pago vencido, o actividad marcada como fraudulenta.

Solución: Revisa la sección de facturación de la consola para confirmar el saldo actual y el motivo exacto de la suspensión, y recarga saldo manualmente o resuelve el motivo indicado antes de reintentar.

La compra de un número queda bloqueada esperando la aprobación del Regulatory Bundle.

Cómo localizarlo: Algunos países revisan manualmente la documentación antes de activar el número, lo que puede tardar cierto tiempo.

Solución: Revisa el estado del Bundle desde la sección de cumplimiento regulatorio de la consola; Twilio notifica por correo cuando se aprueba o si falta algún documento.

Un Usage Trigger configurado no detiene el servicio al superarse el umbral.

Cómo localizarlo: Es el comportamiento esperado y documentado: un Usage Trigger solo envía un webhook de notificación; no suspende la cuenta ni el número por sí mismo salvo que hayas implementado tú mismo esa acción en respuesta al webhook.

Solución: Si necesitas una suspensión efectiva, implementa un pequeño servicio propio que reciba el webhook del Usage Trigger y llame a la API de Twilio para suspender la subcuenta correspondiente, o confía en el saldo prepago sin recarga automática como mecanismo principal de corte.

Comprobación final

Confirma que puedes, usando solo NVDA: explicar la diferencia entre configurar la voz de un número mediante Webhook HTTP y mediante SIP Trunking, generar una API Key restringida y explicar por qué es preferible al Account SID y Auth Token en producción, y explicar con precisión por qué un Usage Trigger de Twilio no equivale, por sí solo, a un límite de gasto vinculante. Si consigues las tres cosas, la comprobación es positiva.

Qué acabas de conseguir

Tienes una referencia completa del proveedor TELÉFONO del sistema —compra de números, Regulatory Bundle, enrutamiento por Webhook o por SIP, seguridad de credenciales y el catálogo de errores de telefonía más relevantes—, junto con una descripción precisa y sin exagerar del control de gasto real que ofrece Twilio.

Ejercicio práctico

Busca en tu propia consola de Twilio la sección de Usage Triggers y crea uno de prueba con un umbral bajo (sin conectarlo a ninguna acción de suspensión real), solo para confirmar por ti mismo, siguiendo el criterio de verificación de esta lección, qué webhook recibe tu servidor y qué información contiene.

Resumen de lo imprescindible

Twilio funciona por pago por uso, con saldo prepago: sin recarga automática, el saldo a 0 actúa como límite vinculante de facto.
Los Usage Triggers notifican al superar un umbral de consumo, pero no suspenden la cuenta por sí solos: la suspensión efectiva requiere una acción propia en respuesta al webhook.
No se ha podido confirmar oficialmente la existencia de un campo de «límite de gasto» de autoservicio distinto del saldo prepago y de los Usage Triggers: no lo des por hecho sin comprobarlo en tu propia consola.
Las API Keys (especialmente las restringidas) son preferibles al Account SID y Auth Token principales para autenticación en producción.
El enrutamiento de voz de un número puede hacerse por Webhook HTTP simple (suficiente para la mayoría de proyectos de este curso) o por SIP Trunking (para integraciones más avanzadas).

Estoy preparado para continuar si puedo…

Comprar y configurar un número con capacidad de voz, incluyendo el Regulatory Bundle si el país lo exige.
Elegir entre enrutamiento por Webhook HTTP y por SIP Trunking según las necesidades del proyecto.
Explicar con precisión qué mecanismos reales de control de gasto ofrece Twilio y cuáles no están confirmados oficialmente.
Diagnosticar los códigos de error de voz más frecuentes (11200, 13224, 21211) y una suspensión de cuenta por saldo.

Fuentes

Última actualización de esta lección: 2026-08-30.

Navegación

Lección anterior: Plan de 30 días para el primer cliente

Volver a la ruta completa del curso

Descargar esta lección en PDF accesible