Migrer Verify depuis un autre fournisseur
Utilisez ce guide pour transférer vos codes de vérification à usage unique par téléphone et par e-mail (OTP) depuis un autre fournisseur de vérification vers Bird Verify. Le portage est réduit, car la surface est réduite : deux appels remplacent la paire create-and-check de votre fournisseur actuel, et Bird gère le code, le message et le canal de livraison derrière eux.
Une différence structurelle détermine la forme du travail. Bird n'a pas d'objet service par application ni d'identifiant de vérification à suivre. Une vérification est identifiée par son destinataire, les deux appels prennent donc le même to, et l'état que votre intégration conserve se réduit à rien.
Checklist de migration :
- Faire correspondre les appels create et check
- Configurer vos canaux, pays et expéditeur
- Porter le cycle de vie de la vérification
- Basculer les webhooks
- Basculer une durée de vie de code à la fois
Les étapes 1 et 3 dépendent du fournisseur que vous quittez. Votre guide fournisseur contient la correspondance champ par champ et la traduction des statuts.
1. Faire correspondre les appels create et check
POST /v1/verify/verifications envoie un code de vérification. La requête minimale est un destinataire :
Exemple de code
curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": {"phone_number": "+15551234567"}}'POST /v1/verify/verifications/check soumet ce que l'utilisateur a saisi, indexé par le même destinataire plus le code. Les charges utiles complètes se trouvent dans Envoi de vérifications.
Quatre différences à gérer pendant le portage :
- Le destinataire est la clé. Les fournisseurs qui renvoient un SID ou un ID de vérification s'attendent à le recevoir lors du check. Bird fait la correspondance sur l'ensemble d'adresses, et celle-ci doit être exacte : une vérification créée avec à la fois un e-mail et un numéro de téléphone n'est pas trouvée par l'un ou l'autre seul. La colonne qui contient l'identifiant de vérification du fournisseur peut être supprimée.
- Un code incorrect renvoie 200. La réponse contient success: false, un reason parmi incorrect_code, expired ou attempts_exhausted, et attempts_remaining. Réservez votre chemin d'erreur aux échecs de requête. Une fois qu'une vérification atteint un état final, les checks suivants renvoient 404 au lieu de success: false.
- Bird génère le code et ne le renvoie jamais. Il n'existe pas de paramètre de code personnalisé, donc une intégration fournisseur qui fournissait son propre code de vérification, ou qui lisait le code pour l'envoyer elle-même, n'a pas d'équivalent ici.
- Les deux endpoints acceptent Idempotency-Key. Un rejeu après un délai d'attente renvoie la réponse originale sans envoyer un autre code ni consommer une tentative.
Les options par requête sont volontairement peu nombreuses : options.code_length et options.channels, qui réordonne ou restreint les canaux pour une requête. Tout le reste est de la configuration d'espace de travail plutôt qu'un champ sur l'envoi.
2. Configurer vos canaux, pays et expéditeur
Bird envoie les codes par e-mail, SMS, WhatsApp et Telegram. Pour un destinataire téléphonique, la plupart des pays essaient d'abord WhatsApp avec SMS en repli, et la livraison passe au canal suivant du plan lorsqu'un envoi échoue. Définissez l'ordre, ou désactivez un canal, par pays sur la page Countries ; désactivez aussi les pays que vous ne servez pas, car une destination inutilisée est une exposition au pumping SMS plutôt qu'une portée supplémentaire.
Deux lacunes méritent d'être vérifiées par rapport à votre flux actuel avant de vous engager sur une date :
- Il n'y a pas de canal d'appel vocal ni d'authentification réseau silencieuse. Un flux qui bascule sur un appel téléphonique pour les utilisateurs qui ne peuvent pas recevoir de SMS nécessite une autre solution ici.
- Choisissez l'expéditeur avant la bascule. Les canaux e-mail, SMS et WhatsApp utilisent par défaut Bird Verify et peuvent utiliser Authifly à la place. Vous pouvez aussi utiliser votre domaine e-mail vérifié, un Sender ID SMS existant ou un numéro WhatsApp connecté avec un modèle d'authentification approuvé. Telegram utilise son propre compte de notification vérifié. Si vous souhaitez conserver un expéditeur SMS que vos utilisateurs reconnaissent déjà, vérifiez qu'il est pris en charge et enregistré dans chaque pays de destination. Expéditeurs et personnalisation couvre les options et le comportement de repli.
Si vous utilisez votre propre numéro WhatsApp, sélectionnez un modèle d'authentification approuvé existant dans votre configuration Verify. Bird contrôle le contenu des e-mails et des messages SMS. Vous ne pouvez pas transmettre un ID de modèle ni un corps de message personnalisé dans une requête de vérification individuelle.
3. Porter le cycle de vie de la vérification
Une vérification reste pending jusqu'à sa résolution : verified quand un code correct arrive dans les temps, failed avec la raison attempts_exhausted ou undeliverable, ou expired avec la raison ttl_elapsed. Faites correspondre les états terminaux de votre fournisseur à ces trois-là, et traitez reason comme un enum ouvert.
Les temporisations qui structurent votre UI sont des paramètres d'espace de travail sur la page Configure : la durée de validité d'un code, le nombre de tentatives de check dont dispose l'utilisateur et la durée du délai de renvoi. Réglez-les pour correspondre à ce que vos utilisateurs connaissent aujourd'hui plutôt que de réécrire le texte de votre UI. La longueur du code est la seule valeur que vous pouvez aussi définir par requête. Les valeurs par défaut et les plages sont dans Paramètres de vérification.
Deux comportements remplacent généralement du code que vous avez déjà :
- Le renvoi est un nouvel appel create. Appelez create avec le même destinataire : pendant le délai de renvoi, il renvoie la vérification en cours sans envoyer, et après, un nouveau code est émis. Chaque code envoyé pour une vérification en cours reste valide jusqu'à la résolution de la vérification, donc un utilisateur qui saisit le premier après l'arrivée du second n'est pas pénalisé.
- "I didn't get a code" a son propre endpoint. POST /v1/verify/verifications/next-channel passe au canal suivant du plan et envoie immédiatement, en ignorant le délai de renvoi mais en conservant l'expiration, le budget de tentatives et la vérification. Reliez-le au bouton plutôt que de boucler des renvois sur un canal qui n'aboutit pas.
Au-dessus de vos paramètres se trouvent des garde-fous de plateforme que vous ne configurez pas : un plafond d'envoi horaire par adresse et un plafond de check par destinataire, tous deux répondus par un 429 et un Retry-After. Si votre fournisseur actuel vous permettait d'augmenter les limites de débit par endpoint et que vous l'avez fait, vérifiez votre pic par rapport aux chiffres dans Garde-fous anti-abus avant la bascule.
4. Basculer les webhooks
Verify émet des événements sur deux axes. Les événements de session, verify.verification.created, verify.verification.verified et verify.verification.failed, suivent la vérification elle-même. Les événements de tentative, verify.attempt.sent, verify.attempt.delivered et verify.attempt.undelivered, suivent chaque envoi individuel de code de vérification : un renvoi ou un basculement de canal ajoute donc des tentatives à la même session. Abonnez un endpoint aux types souhaités avec POST /v1/webhooks ; les payloads sont décrits dans Événements Verify.
Abonnez-vous aux événements de session dont votre intégration a besoin. verify.verification.failed couvre l'impasse de livraison : il se déclenche avec reason: "undeliverable" quand le plan est épuisé et que les échecs enregistrés indiquent qu'aucun code de vérification n'a été envoyé, et son last_attempt_reason nomme l'échec sur le dernier canal essayé. Une vérification qui expire ou qui épuise ses tentatives de vérification n'émet pas d'événement de session : récupérez ces deux issues dans la réponse du check.
Ces événements servent à l'analytique, aux alertes et aux outils de support. Votre décision d'authentification vient de l'appel check, qui répond de manière synchrone ; un flux de connexion ne doit jamais attendre un webhook pour laisser entrer un utilisateur. La livraison est au-moins-une-fois et non ordonnée, signée selon Standard Webhooks : dédupliquez sur le header webhook-id de la même façon que pour tout autre événement Bird.
5. Basculez une durée de vie de code à la fois
Verify n'a pas de destinataires simulés : ce qui vaut la peine d'être testé, c'est l'arrivée du code. Exécutez donc l'intégration avec un numéro de téléphone et une boîte mail que vous contrôlez, sur chaque canal que vous avez activé, avant de toucher à la production.
Le basculement lui-même obéit à une règle facile à oublier. Un code émis par votre ancien fournisseur ne peut pas être vérifié par Bird, et inversement. Basculez donc au niveau de l'appel create, et pendant la durée d'une validité de code, routez chaque check vers le fournisseur qui a émis cette vérification. En pratique :
- Enregistrez quel fournisseur a créé chaque vérification en cours.
- Commencez à envoyer une partie des nouvelles vérifications via Bird, et vérifiez celles-ci auprès de Bird.
- Continuez à vérifier les anciennes vérifications auprès de l'ancien fournisseur jusqu'à l'expiration de la dernière, ce qui prend une fenêtre de validité de code plus une marge.
- Augmentez la part de Bird une fois que les taux de conversion de la première cohorte sont satisfaisants, puis retirez l'ancien chemin.
Surveillez la conversion plutôt que la livraison seule. La page Vérifications et les métriques Verify montrent les envois, les livraisons et le nombre de vérifications ayant atteint verified, c'est-à-dire le chiffre qui vous indique si un ordre de canaux ou une nouvelle identité d'expéditeur vous coûte des inscriptions.
Migrer depuis un fournisseur spécifique
- Twilio Verify : les Services deviennent des paramètres d'espace de travail, VerificationCheck devient un check indexé par le destinataire, traduction des canaux et des statuts
- Prelude : une forme create-and-check quasi identique, avec les signaux de routage et la vérification silencieuse comme éléments non portables
Étapes suivantes
- Envoi de vérifications : le contrat complet de requête et de réponse, les statuts et les limites
- Configuration par pays : ordre des canaux et disponibilité par pays
- Expéditeurs et branding : à quoi ressemble chaque message, et l'expéditeur e-mail personnalisé
- Événements Verify : payloads des événements de session et de tentative
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.