De Twilio a Prelude: Guía Técnica de Migración

Reemplazar tu proveedor de OTP no tiene por qué ser un proyecto de varios sprints. La API unificada Verify de Prelude se adapta directamente a los conceptos de Twilio Verify. Prelude ofrece un único endpoint REST que gestiona todo el ciclo de vida de las OTP, desde la detección de fraude hasta el enrutamiento multicanal. La mayoría de los equipos implementan un reemplazo funcional en un solo sprint.

Qué cambia

A grandes rasgos, vas a sustituir dos entornos de Twilio (Programmable Messaging y Twilio Verify) por una única API de Prelude. La siguiente tabla asocia cada concepto de Twilio con su equivalente en Prelude.

Autenticación

Twilio (antes)

Twilio utiliza autenticación HTTP básica con tu SID de cuenta como usuario y tu token de autenticación como contraseña.

# Twilio – HTTP Basic Auth

curl -X POST https://verify.twilio.com/v2/Services/{ServiceSID}/Verifications \

  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \

  -d 'To=+14155552671' \

  -d 'Channel=sms'

# Twilio – HTTP Basic Auth

curl -X POST https://verify.twilio.com/v2/Services/{ServiceSID}/Verifications \

  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \

  -d 'To=+14155552671' \

  -d 'Channel=sms'

Prelude (después)

Prelude utiliza un token Bearer. Genera una clave de API en el Dashboard, dentro de Settings > API Keys.

# Prelude – Bearer Token

curl -X POST https://api.prelude.dev/v2/verification \

  -H “Authorization: Bearer $PRELUDE_API_KEY” \

  -H 'Content-Type: application/json' \

  -d '{"target": {"type": "phone_number", "value": "+14155552671"}}'

# Prelude – Bearer Token

curl -X POST https://api.prelude.dev/v2/verification \

  -H “Authorization: Bearer $PRELUDE_API_KEY” \

  -H 'Content-Type: application/json' \

  -d '{"target": {"type": "phone_number", "value": "+14155552671"}}'

Enviar una verificación (OTP)

Twilio Verify – antes

// Node.js – Twilio Verify

const client = require('twilio')(accountSid, authToken);



const verification = await client.verify.v2

  .services(verifySid)

  .verifications

  .create({ to: '+14155552671', channel: 'sms' });



console.log(verification.status); // 'pending'

// Node.js – Twilio Verify

const client = require('twilio')(accountSid, authToken);



const verification = await client.verify.v2

  .services(verifySid)

  .verifications

  .create({ to: '+14155552671', channel: 'sms' });



console.log(verification.status); // 'pending'

Prelude – después

// Node.js – Prelude SDK

import Prelude from '@prelude.so/sdk';



const client = new Prelude({ apiToken: process.env.PRELUDE_API_KEY });



const verification = await client.verification.create({

  target: { type: 'phone_number', value: '+14155552671' },

  // Opcional: envía señales digitales para combatir mejor el fraude

  signals: {

    ip: '203.0.113.42',          // IP pública del usuario final

    device_id: 'abc123-unique',   // identificador único y estable del dispositivo

    device_platform: 'ios',

    device_model: 'iPhone 15',

  },

});



console.log(verification.id);     // 'vrf_01...'

console.log(verification.status); // 'success' | 'blocked' | 'challenged'

// Node.js – Prelude SDK

import Prelude from '@prelude.so/sdk';



const client = new Prelude({ apiToken: process.env.PRELUDE_API_KEY });



const verification = await client.verification.create({

  target: { type: 'phone_number', value: '+14155552671' },

  // Opcional: envía señales digitales para combatir mejor el fraude

  signals: {

    ip: '203.0.113.42',          // IP pública del usuario final

    device_id: 'abc123-unique',   // identificador único y estable del dispositivo

    device_platform: 'ios',

    device_model: 'iPhone 15',

  },

});



console.log(verification.id);     // 'vrf_01...'

console.log(verification.status); // 'success' | 'blocked' | 'challenged'

Valores de estado

Prelude devuelve un conjunto de estados más completo al crear una verificación:

Verificar un código de verificación

Twilio Verify – antes

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

  .create({ to: '+14155552671', code: '123456' });




if (check.status === 'approved') {

  // dar acceso

}

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

  .create({ to: '+14155552671', code: '123456' });




if (check.status === 'approved') {

  // dar acceso

}

Prelude – después

// Node.js – Prelude check

const check = await client.verification.check({

  target: { type: 'phone_number', value: '+14155552671' },

  code: '123456',

});




if (check.status === 'success') {

  // dar acceso

}




// Posibles estados: 'success' | 'failure' | ‘expired_or_not_found’

// Node.js – Prelude check

const check = await client.verification.check({

  target: { type: 'phone_number', value: '+14155552671' },

  code: '123456',

});




if (check.status === 'success') {

  // dar acceso

}




// Posibles estados: 'success' | 'failure' | ‘expired_or_not_found’

Gestión de reintentos

En Twilio Verify inicias un reintento creando una nueva verificación para el mismo número dentro del intervalo de reintento del servicio. Prelude funciona exactamente igual: llama de nuevo a POST /v2/verification con el mismo número y Prelude identificará el intervalo de verificación abierto, generando un nuevo intento en lugar de una verificación desde cero.

// Prelude – reintento (misma llamada que create)

const retry = await client.verification.create({

  target: { type: 'phone_number', value: '+14155552671' },

});




// retry.status === 'retry' cuando está dentro del intervalo

// Devuelve 429 Too Many Requests si se alcanza el máximo de intentos

// o si se llama antes del retraso mínimo entre reintentos

// Prelude – reintento (misma llamada que create)

const retry = await client.verification.create({

  target: { type: 'phone_number', value: '+14155552671' },

});




// retry.status === 'retry' cuando está dentro del intervalo

// Devuelve 429 Too Many Requests si se alcanza el máximo de intentos

// o si se llama antes del retraso mínimo entre reintentos

Puedes configurar el número máximo de intentos y la duración del intervalo de verificación desde el Dashboard de Prelude.

Prevención de fraude

Twilio Fraud Guard frente a la prevención integrada de Prelude

Twilio Fraud Guard es un complemento opcional. La prevención de fraude de Prelude está activada por defecto en cada petición, respaldada por modelos de ML y heurísticas entrenadas con decenas de millones de datos en toda la red de Prelude.

Señales recomendadas

Cuantas más señales proporciones, más efectiva será la detección del fraude. La tabla muestra la mejora estimada de conversión según la señal:

Uso de SDKs de Frontend para señales más ricas y huella de red

Instala uno de los SDKs de Frontend de Prelude (Android, iOS, Web, React Native, Flutter) para recopilar señales del dispositivo automáticamente. El SDK captura estos datos y te proporciona un dispatch_id que luego envías a la llamada de verificación en el backend.

// Ejemplo de SDK Web – obtener dispatch_id en el frontend

import { dispatchSignals } from "@prelude.so/js-sdk/signals";




const dispatchId = await dispatchSignals(<tu-clave-sdk-prelude>);




// Backend – enviar dispatch_id para asociar las señales del dispositivo

const verification = await client.verification.create({

target: { type

// Ejemplo de SDK Web – obtener dispatch_id en el frontend

import { dispatchSignals } from "@prelude.so/js-sdk/signals";




const dispatchId = await dispatchSignals(<tu-clave-sdk-prelude>);




// Backend – enviar dispatch_id para asociar las señales del dispositivo

const verification = await client.verification.create({

target: { type

Canales y enrutamiento inteligente

Twilio Verify te obliga a especificar un canal ('sms', 'whatsapp', 'call', 'email') explícitamente. Prelude elige automáticamente el mejor canal y ruta según el coste, la conversión y las señales de fraude, evitándote tener que gestionar esa lógica.

Contenido del mensaje y personalización

Prelude envía la OTP con el siguiente formato:

El mensaje se traduce automáticamente a 32 idiomas según el prefijo del país del número de teléfono. Opciones de personalización disponibles (configurables en el Dashboard o por petición):

• Sufijo de marca – ej. “12345 es tu código de verificación para {nombre_empresa}.”

• Sufijo de seguridad – ej. “No lo compartas.”

• Idioma personalizado – mediante options.locale (formato BCP-47).

• Longitud del código – de 4 a 8 dígitos definido en el Dashboard, anulable con options.code_size.

• Código OTP propio – define tu propio código con options.custom_code (sujeto a aprobación).

• Plantilla PSD2 – plantilla integrada para transacciones PSD2 mediante options.template_id: 'prelude:psd2'.

Webhooks

Twilio – antes

Twilio envía un POST de StatusCallback a la URL que indiques en el Servicio Verify o por petición.

Prelude – después

Define una callback_url para cada petición de verificación.

const verification = await client.verification.create({

  target: {

    type: 'phone_number',

    value: '+14155552671',

  },

  options: {

    callback_url: 'https://your-app.example.com/webhooks/prelude',

  },

});

const verification = await client.verification.create({

  target: {

    type: 'phone_number',

    value: '+14155552671',

  },

  options: {

    callback_url: 'https://your-app.example.com/webhooks/prelude',

  },

});

Tipos de evento

Verificación de firmas

Prelude firma cada webhook con RSASSA-PSS sobre el hash SHA-256 del payload. La firma se incluye en la cabecera X-Webhook-Signature, precedida por rsassa-pss-sha256=. Genera tu clave de firma en el Dashboard.

Lista de IPs permitidas

Añade estas IPs de salida de Prelude en las reglas de tu firewall:

• 34.252.67.209

• 52.30.192.161

• 34.248.153.151

Probar tu integración

Números mágicos de Twilio frente a números de prueba de Prelude

Ambas plataformas ofrecen números especiales sin coste para pruebas automatizadas. En Prelude, se configuran en el Dashboard dentro de Verify API > Configure > Numbers.

Para cada número de prueba defines un código fijo. Solo ese código será aceptado por el endpoint Check, facilitando la creación de flujos de prueba (éxito/fallo) en tu pipeline.

Instalación e inicialización del SDK

Node.js

# Remove Twilio

npm uninstall twilio




# Install Prelude

npm add @prelude.so/sdk

# Remove Twilio

npm uninstall twilio




# Install Prelude

npm add @prelude.so/sdk

import Prelude from '@prelude.so/sdk';




const client = new Prelude({

  apiToken: process.env.PRELUDE_API_KEY,

});

import Prelude from '@prelude.so/sdk';




const client = new Prelude({

  apiToken: process.env.PRELUDE_API_KEY,

});

Python

# Remove Twilio

pip uninstall twilio




# Install Prelude

pip install prelude_python_sdk

# Remove Twilio

pip uninstall twilio




# Install Prelude

pip install prelude_python_sdk

from prelude_python_sdk import Prelude

import os




client = Prelude(api_token=os.environ['PRELUDE_API_KEY'])

from prelude_python_sdk import Prelude

import os




client = Prelude(api_token=os.environ['PRELUDE_API_KEY'])

Go

go get github.com/prelude-so/go-sdk

go get github.com/prelude-so/go-sdk

import (

  "github.com/prelude-so/go-sdk"

  "github.com/prelude-so/go-sdk/option"




client := prelude.NewClient(

  option.WithAPIToken(os.Getenv("PRELUDE_API_KEY")),

)

import (

  "github.com/prelude-so/go-sdk"

  "github.com/prelude-so/go-sdk/option"




client := prelude.NewClient(

  option.WithAPIToken(os.Getenv("PRELUDE_API_KEY")),

)

Java / Kotlin

// build.gradle

implementation("so.prelude.sdk:prelude-java:0.2.0")




// Initialise

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Set API_TOKEN environment variable

// build.gradle

implementation("so.prelude.sdk:prelude-java:0.2.0")




// Initialise

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Set API_TOKEN environment variable

Ruby

# Gemfile

gem 'prelude_sdk'




# Initialise

require 'prelude_sdk'

prelude = PreludeSDK::Client.new(api_token: ENV['API_TOKEN'])

# Gemfile

gem 'prelude_sdk'




# Initialise

require 'prelude_sdk'

prelude = PreludeSDK::Client.new(api_token: ENV['API_TOKEN'])

Lista de control para la migración

Sigue estos pasos para completar con éxito tu migración:

Fase 1 – Configuración

• Crea una cuenta de Prelude en app.prelude.so e inicia sesión en el Dashboard.

• Genera una clave de API en Dashboard > Configure > API Keys.

• Añade PRELUDE_API_KEY a tu gestor de secretos o variables de entorno.

• Instala el SDK de Prelude correspondiente a tu lenguaje de programación (ver Sección 12).

• Configura los números de prueba en Dashboard > Verify API > Configure > Numbers.

Fase 2 – Cambios en el código

• Sustituye la inicialización del SDK de Twilio por el de Prelude (ver Sección 12).

• Cambia verifications.create(...) por client.verification.create(...).

• Cambia verificationChecks.create(...) por client.verification.check(...).

• Actualiza las comprobaciones de estado de 'approved' a 'success' y de 'pending' a 'success'.

• Elimina el parámetro channel: Prelude selecciona el canal idóneo automáticamente.

• Elimina las referencias a ServiceSID.

• Añade señales de fraude (signals.ip, signals.device_id, etc.) en las llamadas de creación de verificación.

• Actualiza la lógica del webhook para procesar los eventos de Prelude (ver Sección 10.3).

• Implementa la verificación de firma en tus webhooks (RSASSA-PSS, ver Sección 10.4).

Fase 3 – Pruebas

• Realiza una prueba completa end-to-end en tu entorno de staging con un número de teléfono real.

• Verifica que los webhooks se reciban y procesen correctamente.

• Confirma que los escenarios bloqueados o con sospecha de fraude devuelven el estado esperado.

Fase 4 – Despliegue progresivo

• Despliega en producción (se aconseja usar un feature flag o canary).

• Monitorea las tasas de conversión y bloqueo directamente en el Dashboard de Prelude.

• Elimina definitivamente las credenciales antiguas de Twilio de tu gestor de secretos.

Guía rápida de códigos de error

Prelude utiliza códigos de estado HTTP estándar. La respuesta contiene un objeto JSON con los campos de código y descripción.

Recursos y soporte

• Documentación técnica: https://docs.prelude.so

• Dashboard: https://app.prelude.so

• Estado del servicio: https://status.prelude.so

• Contacto de soporte: support@prelude.so