Migrating From Twilio to Prelude: A Technical Guide

Remplacer votre fournisseur d'OTP ne doit pas nécessairement être un projet multi-sprint. L'API Verify unifiée de Prelude se calque directement sur les concepts de Twilio Verify. Prelude fournit un point de terminaison REST unique qui gère l'ensemble du cycle de vie des OTP, de la détection de la fraude au routage multi-canal. La plupart des équipes déploient une solution de remplacement fonctionnelle en un seul sprint.

Ce qui change

À haut niveau, vous remplacez deux interfaces Twilio : Programmable Messaging et Twilio Verify par une seule API Prelude. Le tableau ci-dessous associe chaque concept Twilio à son équivalent Prelude.

Authentification

Twilio (avant)

Twilio utilise l'authentification HTTP Basic avec votre SID de compte comme identifiant et votre jeton de sécurité comme mot de passe.

# 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 (après)

Prelude utilise un jeton Bearer. Générez une clé API dans le Dashboard sous 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"}}'

Envoi d'une vérification (OTP)

Twilio Verify – avant

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

  // Optionnel : transmettre des signaux digitaux pour mieux contrer la fraude

  signals: {

    ip: '203.0.113.42',          // IP publique de l'utilisateur final

    device_id: 'abc123-unique',   // identifiant unique et stable du périphérique

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

  // Optionnel : transmettre des signaux digitaux pour mieux contrer la fraude

  signals: {

    ip: '203.0.113.42',          // IP publique de l'utilisateur final

    device_id: 'abc123-unique',   // identifiant unique et stable du périphérique

    device_platform: 'ios',

    device_model: 'iPhone 15',

  },

});



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

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

Valeurs de statut

Prelude renvoie un ensemble de statuts plus riche lors du lancement d'une vérification :

Vérification d'un code de validation

Twilio Verify – avant

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

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




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

  // accorder l'accès

}

// Node.js – Twilio Verify check

const check = await client.verify.v2

  .services(verifySid)

  .verificationChecks

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




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

  // accorder l'accès

}

Prelude – après

// Node.js – Prelude check

const check = await client.verification.check({

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

  code: '123456',

});




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

  // accorder l'accès

}




// Statuts possibles : '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') {

  // accorder l'accès

}




// Statuts possibles : 'success' | 'failure' | ‘expired_or_not_found’

Gestion des nouvelles tentatives (Retries)

Dans Twilio Verify, vous lancez une nouvelle tentative en créant une nouvelle vérification pour le même numéro de téléphone au cours de la fenêtre temporelle de retry définie dans le service. Prelude fonctionne de la même manière : appelez à nouveau POST /v2/verification avec le même numéro de téléphone et Prelude détectera la fenêtre de vérification ouverte pour émettre une nouvelle tentative plutôt qu'une toute nouvelle session.

// Prelude – retry (même appel que pour la création)

const retry = await client.verification.create({

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

});




// retry.status === 'retry' lorsque l'on est dans la fenêtre temporelle

// Renvoie 429 Too Many Requests si le nombre max de tentatives est atteint

// ou si l'appel est effectué avant le délai minimum entre deux essais

// Prelude – retry (même appel que pour la création)

const retry = await client.verification.create({

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

});




// retry.status === 'retry' lorsque l'on est dans la fenêtre temporelle

// Renvoie 429 Too Many Requests si le nombre max de tentatives est atteint

// ou si l'appel est effectué avant le délai minimum entre deux essais

Vous pouvez configurer le nombre maximal de tentatives ainsi que la durée de la fenêtre de vérification depuis votre Dashboard Prelude.

Prévention de la fraude

Twilio Fraud Guard vs. dispositif natif de Prelude

Twilio Fraud Guard est un module complémentaire optionnel. La prévention contre la fraude de Prelude est quant à elle activée par défaut pour chaque requête, propulsée par des modèles de ML et des heuristiques entraînés sur des dizaines de millions de données à travers tout le réseau de Prelude.

Signaux à transmettre

Plus vous fournissez de signaux, plus la détection de la fraude gagne en efficacité. Le tableau ci-dessous estime la hausse du taux de conversion par signal fourni :

Utilisation des SDK Frontend pour des signaux enrichis et l'empreinte réseau

Installez l'un des SDK Frontend de Prelude (Android, iOS, Web, React Native, Flutter) pour collecter automatiquement les données de l'appareil. Le SDK récupère automatiquement les signaux et vous fournit un dispatch_id à transmettre lors de l'appel de vérification en backend.

// Exemple SDK Web – récupération du dispatch_id côté frontend

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




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




// Backend – envoi du dispatch_id pour lier les signaux de l'appareil

const verification = await client.verification.create({

target: { type

// Exemple SDK Web – récupération du dispatch_id côté frontend

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




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




// Backend – envoi du dispatch_id pour lier les signaux de l'appareil

const verification = await client.verification.create({

target: { type

Canaux & Multi-Routage

Twilio Verify requiert de spécifier explicitement un canal ('sms', 'whatsapp', 'call', 'email'). Prelude quant à lui sélectionne automatiquement la meilleure option et la route optimale selon le coût, le taux de conversion et les indices de fraude, vous évitant de devoir concevoir la logique de sélection des opérateurs ou des canaux.

Contenu des messages & Personnalisation

Prelude envoie l'OTP sous la forme suivante :

Le message est traduit automatiquement dans 32 langues en se basant sur l'indicatif pays du numéro de téléphone. Options de personnalisation disponibles (paramétrables sur le Dashboard ou à la demande) :

• Suffixe de marque – ex. “12345 est votre code de vérification pour {nom de l'entreprise}.”

• Avertissement de sécurité – ex. “Ne le partagez pas.”

• Langue spécifique – via options.locale (format BCP-47).

• Longueur du code – de 4 à 8 chiffres défini sur le Dashboard, peut être écrasé via options.code_size.

• Code OTP personnalisé – fournissez votre propre code via options.custom_code (soumis à validation).

• Modèle PSD2 – modèle conforme pour les transactions PSD2 via options.template_id: 'prelude:psd2'.

Webhooks

Twilio – avant

Twilio envoie un POST StatusCallback vers l'URL que vous indiquez sur le service de vérification ou par requête.

Prelude – après

Renseignez un callback_url par requête de vérification.

const verification = await client.verification.create({

  target: {

    type: 'phone_number',

    value: '+14155552671',

  },

  options: {

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

  },

});

const verification = await client.verification.create({

  target: {

    type: 'phone_number',

    value: '+14155552671',

  },

  options: {

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

  },

});

Types d'événements

Contrôle des signatures

Prelude signe l'ensemble des webhooks en employant RSASSA-PSS sur le hash SHA-256 du payload. La signature se situe dans l'en-tête X-Webhook-Signature, précédée de rsassa-pss-sha256=. Créez une clé de signature depuis votre Dashboard.

Liste d'IP autorisées (Allowlist)

Ajoutez ces adresses IP de sortie de Prelude à votre pare-feu :

• 34.252.67.209

• 52.30.192.161

• 34.248.153.151

Tester votre intégration

Numéros magiques Twilio vs. numéros de test Prelude

Les deux plateformes mettent à disposition des numéros réservés pour les tests automatisés, exempts de facturation. Chez Prelude, ces numéros de test se configurent via le Dashboard dans Verify API > Configure > Numbers.

Pour chaque numéro de test, vous pré-définissez un code fixe. Seul ce code sera validé par l'endpoint Check, facilitant l'écriture de scénarios succès/échec dans vos suites de tests.

Installation & Initialisation du SDK

Node.js

# Retirer Twilio

npm uninstall twilio




# Installer Prelude

npm add @prelude.so/sdk

# Retirer Twilio

npm uninstall twilio




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

# Retirer Twilio

pip uninstall twilio




# Installer Prelude

pip install prelude_python_sdk

# Retirer Twilio

pip uninstall twilio




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




// Initialisation

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Définir la variable d'environnement API_TOKEN

// build.gradle

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




// Initialisation

PreludeClient client = PreludeOkHttpClient.fromEnv();

// Définir la variable d'environnement API_TOKEN

Ruby

# Gemfile

gem 'prelude_sdk'




# Initialisation

require 'prelude_sdk'

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

# Gemfile

gem 'prelude_sdk'




# Initialisation

require 'prelude_sdk'

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

Checklist de migration

Parcourez chaque étape ci-dessous pour finaliser votre transition :

Phase 1 – Initialisation

• Inscrivez-vous sur app.prelude.so et connectez-vous sur le Dashboard.

• Générez une clé d'API via Dashboard > Configure > API Keys.

• Ajoutez PRELUDE_API_KEY dans votre gestionnaire de secrets / de variables d'environnement.

• Installez le SDK Prelude correspondant à votre langage (voir Section 12).

• Configurez vos numéros de test sous Dashboard > Verify API > Configure > Numbers.

Phase 2 – Ajustements du code

• Remplacez l'initialisation du SDK Twilio par celle de Prelude (voir Section 12).

• Remplacez verifications.create(...) par client.verification.create(...).

• Remplacez verificationChecks.create(...) par client.verification.check(...).

• Modifiez vos validations de statut de 'approved' à 'success' et de 'pending' à 'success'.

• Retirez le paramètre channel – Prelude sélectionne automatiquement le meilleur canal.

• Supprimez les références de type ServiceSID.

• Transmettez les signaux liés à la fraude (signals.ip, signals.device_id, etc.) lors de l'appel de création.

• Mettez à jour le gestionnaire de webhooks pour intercepter les types d'événements Prelude (voir Section 10.3).

• Intégrez la validation des signatures de webhooks (RSASSA-PSS, voir Section 10.4).

Phase 3 – Phase de test

• Exécutez un test complet de bout en bout en pré-production à l'aide d'un véritable numéro de téléphone.

• Validez la bonne réception des webhooks ainsi que la lecture du payload.

• Vérifiez que les flux de blocage/fraude renvoient bien le statut prévu.

Phase 4 – Déploiement

• Déployez en production (un déploiement progressif ou par feature flags est fortement conseillé).

• Surveillez de près vos taux de conversion et de blocage depuis le Dashboard Prelude.

• Supprimez vos anciennes informations d'identification Twilio de votre gestionnaire de secrets.

Référentiel des codes d'erreur

Prelude tire parti des codes d'état HTTP conventionnels. Le corps de réponse encapsule un objet JSON contenant les clés code et message.

Support & Ressources

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

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

• Page de statut : https://status.prelude.so

• Adresse de support : support@prelude.so