Twilio para JavaScript (Node.js): guía completa con ejemplos

1. ¿Qué es y para qué sirve?

Twilio es una plataforma en la nube de tipo Communications Platform as a Service (CPaaS) que proporciona a los desarrolladores interfaces de programación (API) para integrar funciones de voz, SMS, MMS, video y autenticación (2FA) en aplicaciones web y móviles. La librería twilio para Node.js es el SDK oficial que abstrae la complejidad de las solicitudes HTTP directas a la API REST de Twilio, ofreciendo una interfaz cómoda y con seguridad de tipos para trabajar con todos los servicios de la plataforma.

¿Para qué sirve? En el mundo actual, la comunicación es esencial para cualquier negocio. Twilio permite a los desarrolladores añadir rápidamente funciones como el envío de notificaciones por SMS, la realización de llamadas automáticas (por ejemplo, para confirmar pedidos o recordar citas), la creación de menús de voz interactivos (IVR) y mucho más, sin necesidad de grandes inversiones en infraestructura. En lugar de desplegar y mantener tu propia red de operadores, accedes a una red global a través de una API sencilla.

La librería para Node.js es especialmente popular gracias a la naturaleza asíncrona de JavaScript y la amplia adopción de Node.js en el desarrollo backend. Soporta Promesas y async/await, lo que hace que el código sea limpio y legible. El SDK maneja automáticamente los reintentos en caso de errores de red, gestiona la autenticación mediante Account SID y Auth Token, e incluye tipos integrados para TypeScript, lo que facilita enormemente el desarrollo y la depuración.

2. Instalación

La instalación de la librería se realiza a través del gestor de paquetes npm. Asegúrate de tener Node.js versión 14 o superior instalado.

npm install twilio

Para usar TypeScript, no es necesario instalar tipos adicionales, ya que la librería incluye definiciones de tipos integradas.

npm install twilio @types/twilio

Después de la instalación, puedes importar la librería en tu proyecto:

const twilio = require('twilio'); // CommonJS
// o
import twilio from 'twilio'; // ES Modules

3. Inicio rápido — ejemplo mínimo funcional

Antes de empezar, necesitarás tus credenciales de la consola de Twilio: Account SID y Auth Token. También deberás adquirir un número de teléfono en el panel de control de Twilio.

// Importamos la librería
const twilio = require('twilio');

// Tus credenciales de la consola de Twilio
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Reemplaza con tu SID
const authToken = 'tu_auth_token'; // Reemplaza con tu token

// Creamos una instancia del cliente
const client = twilio(accountSid, authToken);

// Enviamos un SMS
client.messages
  .create({
    body: '¡Hola, mundo! Este es un mensaje de prueba desde Twilio.',
    from: '+1234567890', // Tu número de Twilio
    to: '+0987654321'    // Número del destinatario
  })
  .then(message => console.log('Mensaje enviado. SID:', message.sid))
  .catch(error => console.error('Error:', error));

Este ejemplo mínimo envía un mensaje SMS. Tras el envío exitoso, se mostrará en la consola el identificador único del mensaje (SID).

4. Métodos/funciones/clases principales

4.1. client.messages.create()

Firma: client.messages.create(params: MessageCreateParams): Promise<MessageInstance>

Descripción: Envía un mensaje SMS o MMS. Los parámetros incluyen body (texto), from (número del remitente), to (número del destinatario) y los opcionales mediaUrl (para MMS) y statusCallback.

client.messages
  .create({
    body: 'Tu código de verificación es: 1234',
    from: '+1234567890',