Migrazione da Twilio a Prelude: guida tecnica

Sostituire il tuo provider di OTP non deve essere per forza un progetto che richiede più sprint. L'API Verify unificata di Prelude si mappa direttamente sui concetti di Twilio Verify. Prelude fornisce un singolo endpoint REST che gestisce l'intero ciclo di vita degli OTP, dal rilevamento delle frodi al routing multicanale. La maggior parte dei team rilascia un'alternativa funzionante in un singolo sprint.

Cosa cambia

A grandi linee, andrai a sostituire due servizi di Twilio (Programmable Messaging e Twilio Verify) con una singola API di Prelude. La tabella seguente mappa ogni concetto di Twilio con il suo equivalente in Prelude.

Autenticazione

Twilio (prima)

Twilio utilizza l'autenticazione HTTP Basic con il tuo Account SID come nome utente e l'Auth Token come password.

# 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 (dopo)

Prelude utilizza un Bearer token. Genera una API key nella Dashboard sotto Impostazioni > 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"}}'

Invio di una verifica (OTP)

Twilio Verify – prima

// 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 – dopo

// 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' },

  // Opzionale: invia segnali digitali per combattere meglio le frodi

  signals: {

    ip: '203.0.113.42',          // IP pubblico dell'utente finale

    device_id: 'abc123-unique',   // identificativo univoco e stabile 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' },

  // Opzionale: invia segnali digitali per combattere meglio le frodi

  signals: {

    ip: '203.0.113.42',          // IP pubblico dell'utente finale

    device_id: 'abc123-unique',   // identificativo univoco e stabile del dispositivo

    device_platform: 'ios',

    device_model: 'iPhone 15',

  },

});



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

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

Valori di stato

Prelude restituisce un insieme più ricco di stati durante la creazione di una verifica:

Controllo di un codice di verifica

Twilio Verify – prima

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

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




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

  // consenti l'accesso

}

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

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




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

  // consenti l'accesso

}

Prelude – dopo

// Node.js – Prelude check

const check = await client.verification.check({

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

  code: '123456',

});




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

  // consenti l'accesso

}




// Stati possibili: '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') {

  // consenti l'accesso

}




// Stati possibili: 'success' | 'failure' | ‘expired_or_not_found’

Gestione dei tentativi di rinvio

In Twilio Verify si avvia un nuovo tentativo creando una nuova verifica per lo stesso numero di telefono all'interno della finestra di rinvio del servizio. Prelude funziona allo stesso modo: chiama nuovamente POST /v2/verification con lo stesso numero di telefono e Prelude riconoscerà la finestra di verifica aperta, effettuando un nuovo tentativo invece di creare una nuova verifica da zero.

// Prelude – retry (stessa chiamata di create)

const retry = await client.verification.create({

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

});




// retry.status === 'retry' se all'interno della finestra temporale

// Restituisce 429 Too Many Requests se viene raggiunto il numero massimo di tentativi

// o se viene chiamato prima dell'intervallo minimo tra i rinvii

// Prelude – retry (stessa chiamata di create)

const retry = await client.verification.create({

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

});




// retry.status === 'retry' se all'interno della finestra temporale

// Restituisce 429 Too Many Requests se viene raggiunto il numero massimo di tentativi

// o se viene chiamato prima dell'intervallo minimo tra i rinvii

Puoi configurare il numero massimo di tentativi e la durata della finestra di verifica direttamente dalla Dashboard di Prelude.

Prevenzione delle frodi

Twilio Fraud Guard vs. Prevenzione integrata di Prelude

Twilio Fraud Guard è un add-on opzionale. La prevenzione delle frodi di Prelude è invece attiva di default per ogni richiesta, alimentata da modelli di ML ed euristiche addestrate su decine di milioni di data point in tutta la rete di Prelude.

Segnali da trasmettere

Più segnali fornisci, più efficace sarà il rilevamento delle frodi. La tabella seguente mostra l'aumento stimato della conversione per ciascun segnale:

Utilizzo degli SDK Frontend per segnali più ricchi e fingerprinting di rete

Installa uno degli SDK Frontend di Prelude (Android, iOS, Web, React Native, Flutter) per raccogliere automaticamente i segnali del dispositivo. L'SDK acquisisce i segnali in automatico e ti fornisce un dispatch_id da passare alla chiamata di verifica sul backend.

// Esempio Web SDK – ottieni il dispatch_id sul frontend

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




const dispatchId = await dispatchSignals(<your-prelude-sdk-key>);




// Backend – passa il dispatch_id per collegare i segnali del dispositivo

const verification = await client.verification.create({

target: { type

// Esempio Web SDK – ottieni il dispatch_id sul frontend

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




const dispatchId = await dispatchSignals(<your-prelude-sdk-key>);




// Backend – passa il dispatch_id per collegare i segnali del dispositivo

const verification = await client.verification.create({

target: { type

Canali e Multi-Routing

Twilio Verify richiede di specificare esplicitamente un canale ('sms', 'whatsapp', 'call', 'email'). Prelude sceglie automaticamente il canale e la rotta migliori in base al costo, al tasso di conversione e ai segnali di frode, eliminando la necessità di gestire logiche di selezione dell'operatore o del canale.

Contenuto del messaggio e personalizzazione

Prelude invia l'OTP nel formato:

Il messaggio viene tradotto automaticamente in 32 lingue in base al prefisso internazionale del numero di telefono. Opzioni di personalizzazione disponibili (configurabili nella Dashboard o per singola richiesta):

• Suffisso del brand – ad es. “12345 è il tuo codice di verifica per {nome azienda}.”

• Suffisso di sicurezza – ad es. “Non condividerlo.”

• Lingua personalizzata – tramite options.locale (formato BCP-47).

• Lunghezza del codice – da 4 a 8 cifre impostata nella Dashboard, sovrascrivibile tramite options.code_size.

• Codice OTP personalizzato – inserisci il tuo codice tramite options.custom_code (soggetto ad approvazione).

• Template PSD2 – template integrato per le transazioni PSD2 tramite options.template_id: 'prelude:psd2'.

Webhook

Twilio – prima

Twilio invia una richiesta POST StatusCallback all'URL specificato nel Verify Service o per singola richiesta.

Prelude – dopo

Specifica un callback_url per ogni richiesta di verifica.

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',

  },

});

Tipi di eventi

Verifica della firma

Prelude firma ogni webhook con RSASSA-PSS sull'hash SHA-256 del payload. La firma è presente nell'header X-Webhook-Signature, preceduta da rsassa-pss-sha256=. Genera una chiave di firma nella Dashboard.

IP consentiti (allowlist)

Inserisci questi IP di uscita di Prelude nella whitelist del tuo firewall:

• 34.252.67.209

• 52.30.192.161

• 34.248.153.151

Testare la tua integrazione

Numeri magici di Twilio vs. numeri di test di Prelude

Entrambe le piattaforme forniscono numeri di telefono speciali per test automatizzati che non generano costi. In Prelude, i numeri di test si configurano nella Dashboard sotto Verify API > Configure > Numbers.

Per ogni numero di test definisci un codice fisso. Solo quel codice verrà accettato dall'endpoint Check, consentendoti di creare script per scenari di successo/fallimento nella tua suite di test.

Installazione e inizializzazione dell'SDK

Node.js

# Rimuovi Twilio

npm uninstall twilio




# Installa Prelude

npm add @prelude.so/sdk

# Rimuovi Twilio

npm uninstall twilio




# Installa 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

# Rimuovi Twilio

pip uninstall twilio




# Installa Prelude

pip install prelude_python_sdk

# Rimuovi Twilio

pip uninstall twilio




# Installa 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")




// Inizializza

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Imposta la variabile d'ambiente API_TOKEN

// build.gradle

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




// Inizializza

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Imposta la variabile d'ambiente API_TOKEN

Ruby

# Gemfile

gem 'prelude_sdk'




# Inizializza

require 'prelude_sdk'

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

# Gemfile

gem 'prelude_sdk'




# Inizializza

require 'prelude_sdk'

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

Checklist di migrazione

Segui ogni passaggio riportato sotto per completare la migrazione:

Fase 1 – Configurazione

• Crea un account Prelude su app.prelude.so e accedi alla Dashboard.

• Genera una API key in Dashboard > Configure > API Keys.

• Aggiungi PRELUDE_API_KEY al tuo gestore dei segreti / variabili d'ambiente.

• Installa l'SDK di Prelude per il tuo linguaggio di programmazione (vedi Sezione 12).

• Configura i numeri di test in Dashboard > Verify API > Configure > Numbers.

Fase 2 – Modifiche al codice

• Sostituisci l'inizializzazione dell'SDK di Twilio con quello di Prelude (vedi Sezione 12).

• Sostituisci verifications.create(...) con client.verification.create(...).

• Sostituisci verificationChecks.create(...) con client.verification.check(...).

• Aggiorna i controlli di stato da 'approved' a 'success' e da 'pending' a 'success'.

• Rimuovi il parametro channel – Prelude seleziona automaticamente il canale migliore.

• Rimuovi i riferimenti a ServiceSID.

• Aggiungi i segnali di frode (signals.ip, signals.device_id, ecc.) alle chiamate di creazione della verifica.

• Aggiorna il gestore dei webhook per i tipi di evento di Prelude (vedi Sezione 10.3).

• Implementa la verifica della firma dei webhook (RSASSA-PSS, vedi Sezione 10.4).

Fase 3 – Test

• Esegui un test end-to-end completo in ambiente di staging con un numero di telefono reale.

• Verifica la consegna dei webhook e il corretto parsing dei payload.

• Conferma che gli scenari bloccati o fraudolenti restituiscano lo stato previsto.

Fase 4 – Rilascio

• Rilascia in produzione (si consiglia l'uso di un feature flag o di un rilascio canary).

• Monitora i tassi di conversione e di blocco nella Dashboard di Prelude.

• Rimuovi le vecchie credenziali di Twilio dal gestore dei segreti.

Riferimento codici di errore

Prelude utilizza i codici di stato HTTP standard. Il corpo della risposta contiene un oggetto JSON con i campi code e message.

Supporto e risorse

• Documentazione: https://docs.prelude.so

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

• Pagina di stato: https://status.prelude.so

• Email di supporto: support@prelude.so