Verify migreren vanaf een andere provider
Gebruik deze handleiding om eenmalige verificatiecodes via telefoon en e-mail (OTP) van een andere verificatieprovider naar Bird Verify te verplaatsen. De migratie is klein, omdat het oppervlak klein is: twee calls vervangen wat het create-en-check-paar van je provider er ook uitziet, en Bird beheert de code, het bericht en het afleverkanaal erachter.
Eén structureel verschil bepaalt de opzet van het werk. Bird heeft geen service-object per applicatie en geen verificatie-ID dat je hoeft bij te houden. Een verificatie wordt geïdentificeerd aan de hand van de ontvanger, dus beide calls nemen dezelfde to, en de state die je integratie bijhoudt krimpt tot niets.
De migratiechecklist:
- Breng de create- en check-calls in kaart
- Stel je kanalen, landen en afzender in
- Porteer de verificatielevenscyclus
- Schakel webhooks over
- Migreer per codelevensduur
Stap 1 en 3 hangen af van welke provider je verlaat. Je providergids bevat de veld-voor-veld-mapping en de statusvertaling.
1. Breng de create- en check-calls in kaart
POST /v1/verify/verifications verstuurt een verificatiecode. Het kleinste verzoek is een ontvanger:
Codevoorbeeld
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 verstuurt wat de gebruiker heeft ingetypt, op basis van dezelfde ontvanger plus de code. De volledige payloads staan in Verificaties versturen.
Vier verschillen om rekening mee te houden bij het porten:
- De ontvanger is de sleutel. Providers die een verificatie-SID of -ID teruggeven, verwachten dat bij de check. Bird matcht in plaats daarvan op de adresset, en die moet exact overeenkomen: een verificatie die is aangemaakt met zowel een e-mailadres als een telefoonnummer wordt niet gevonden met slechts één van beide. De kolom die het verificatie-ID van de provider bevat kun je verwijderen.
- Een verkeerde code geeft 200 terug. Het antwoord bevat success: false, een reason van incorrect_code, expired of attempts_exhausted, en attempts_remaining. Reserveer je foutpad voor mislukte verzoeken. Zodra een verificatie een eindstatus bereikt, geven verdere checks 404 terug in plaats van success: false.
- Bird genereert de code en geeft die nooit terug. Er is geen custom-code-parameter, dus een providerintegratie die een eigen verificatiecode meegaf, of de code terugleesde om die zelf te versturen, heeft hier geen equivalent.
- Beide endpoints accepteren Idempotency-Key. Een replay na een timeout geeft het oorspronkelijke antwoord terug zonder een nieuwe code te versturen of een poging te verbruiken.
Per-request-opties zijn bewust beperkt: options.code_length en options.channels, waarmee je de kanalen voor één verzoek herschikt of beperkt. Al het andere is werkruimteconfiguratie in plaats van een veld op de verstuuractie.
2. Stel je kanalen, landen en afzender in
Bird levert codes af via e-mail, SMS, WhatsApp en Telegram. Voor een telefoongeadresseerde proberen de meeste landen eerst WhatsApp met SMS als terugvaloptie, en de aflevering gaat door naar het volgende kanaal in het plan wanneer een verzending mislukt. Stel de volgorde in, of schakel een kanaal uit, per land op de Countries-pagina; schakel de landen die je niet bedient meteen uit, want een ongebruikte bestemming is blootstelling aan SMS-pumping in plaats van bereik.
Twee hiaten zijn het waard om te controleren tegen je huidige flow voordat je een datum vastlegt:
- Er is geen spraakoproepkanaal en geen stille netwerkauthenticatie. Een flow die terugvalt op een telefoonoproep voor gebruikers die geen SMS kunnen ontvangen, heeft hier een andere oplossing nodig.
- Kies de afzender vóór de cutover. E-mail, SMS en WhatsApp gebruiken standaard Bird Verify en kunnen in plaats daarvan Authifly gebruiken. Je kunt ook je geverifieerde e-maildomein, een bestaand SMS Sender ID of een gekoppeld WhatsApp-nummer met een goedgekeurd authenticatietemplate gebruiken. Telegram gebruikt een eigen geverifieerd notificatieaccount. Als je een SMS-afzender wilt behouden die je gebruikers al herkennen, controleer dan of deze wordt ondersteund en geregistreerd is in elk bestemmingsland. Afzenders en branding behandelt de keuzes en het fallbackgedrag.
Als je je eigen WhatsApp-nummer gebruikt, selecteer dan een bestaand goedgekeurd authenticatietemplate in je Verify-configuratie. Bird beheert de e-mail- en SMS-berichttekst. Je kunt geen template-ID of aangepaste berichttekst meegeven bij een individueel verificatieverzoek.
3. Porteer de verificatielevenscyclus
Een verificatie is pending totdat ze wordt afgerond: verified wanneer een correcte code op tijd binnenkomt, failed met reden attempts_exhausted of undeliverable, of expired met reden ttl_elapsed. Vertaal de eindstatussen van je provider naar die drie, en behandel reason als een open enum.
De timings die je UI bepalen zijn werkruimte-instellingen op de Configure-pagina: hoe lang een code geldig blijft, hoeveel checkpogingen een gebruiker krijgt, en hoe lang de cooldown voor opnieuw versturen duurt. Stel ze in zodat ze overeenkomen met wat je gebruikers nu ervaren, in plaats van je UI-tekst te herschrijven. Codelengte is de enige waarde die je ook per verzoek kunt instellen. De standaardwaarden en bereiken staan in Verificatie-instellingen.
Twee gedragingen vervangen meestal code die je al hebt:
- Opnieuw versturen is nogmaals de create-call. Roep create aan met dezelfde ontvanger: binnen de cooldown geeft het de actieve verificatie terug zonder te versturen, en daarna gaat er een nieuwe code uit. Elke code die is verstuurd voor een actieve verificatie blijft geldig totdat de verificatie wordt afgerond, dus een gebruiker die de eerste code invoert nadat de tweede is aangekomen, wordt daar niet voor gestraft.
- "I didn't get a code" heeft een eigen endpoint. POST /v1/verify/verifications/next-channel gaat door naar het volgende kanaal in het plan en verstuurt daar direct, waarbij de cooldown voor opnieuw versturen wordt genegeerd maar de vervaltijd, het pogingsbudget en de verificatie behouden blijven. Koppel het aan de knop in plaats van herhaaldelijk te versturen op een kanaal dat niet aankomt.
Bovenop je instellingen zitten platformbeveiligingen die je niet configureert: een limiet per adres per uur voor versturen en een limiet per ontvanger voor checks, beide beantwoord met een 429 en een Retry-After. Als je huidige provider je per-endpoint-limieten liet verhogen en je dat hebt gedaan, controleer dan je piek tegen de cijfers in Misbruikbeveiligingen vóór de migratie.
4. Schakel webhooks over
Verify zendt events uit op twee assen. Sessie-events, verify.verification.created, verify.verification.verified en verify.verification.failed, volgen de verificatie zelf. Poging-events, verify.attempt.sent, verify.attempt.delivered en verify.attempt.undelivered, volgen elke individuele verificatiecodeversturing, dus een opnieuw versturen of een kanaalfailover voegt pogingen toe aan dezelfde sessie. Abonneer een endpoint op de typen die je wilt met POST /v1/webhooks; de payloads staan in Verify events.
Abonneer je op de sessie-events die je integratie nodig heeft. verify.verification.failed dekt het doodlopende bezorgpad: het vuurde met reason: "undeliverable" wanneer het plan is uitgeput en de geregistreerde fouten aangeven dat er geen verificatiecode is verstuurd, en last_attempt_reason bevat de fout op het laatst geprobeerde kanaal. Een verificatie die verloopt of haar checkpogingen uitput, zendt geen sessie-event uit, dus haal die twee uitkomsten uit het check-antwoord.
Deze events dienen voor analytics, alerting en supporttooling. Je authenticatiebeslissing komt van de check-call, die synchroon antwoordt, en een loginflow mag nooit op een webhook wachten om een gebruiker binnen te laten. Bezorging is at-least-once en ongeordend, ondertekend volgens Standard Webhooks, dus deduplicate op de webhook-id-header op dezelfde manier als bij elk ander Bird-event.
5. Schakel over met één codelevensduur tegelijk
Verify heeft geen gesimuleerde ontvangers: wat je wilt testen is dat de code aankomt, dus voer de integratie uit tegen een telefoonnummer en een mailbox die je beheert, op elk kanaal dat je hebt ingeschakeld, voordat je productie aanraakt.
De overschakeling zelf heeft één regel die je makkelijk mist. Een code die je oude provider heeft uitgegeven, kan niet door Bird worden gecontroleerd, en andersom. Schakel dus over bij de create-call, en routeer gedurende de duur van één codelevensduur elke check naar de provider die die verificatie heeft uitgegeven. In de praktijk:
- Registreer welke provider elke actieve verificatie heeft aangemaakt.
- Begin een deel van de nieuwe verificaties via Bird te versturen en check die tegen Bird.
- Blijf oudere verificaties tegen de oude provider checken totdat de laatste verloopt; dat kost één geldigheidsvenster van de code plus een marge.
- Verhoog het aandeel van Bird zodra de conversiepercentages van de eerste groep er goed uitzien, en zet daarna het oude pad uit.
Let op conversie, niet alleen op bezorging. De Verifications-pagina en de Verify-metrics tonen versturingen, bezorgingen en hoeveel verificaties verified bereikten; dat is het getal dat je vertelt of een kanaalvolgorde of een nieuwe afzenderidentiteit je aanmeldingen kost.
Migreren vanaf een specifieke provider
- Twilio Verify: Services worden werkruimte-instellingen, VerificationCheck wordt een op ontvanger gebaseerde check, kanaal- en statusvertaling
- Prelude: een vrijwel identieke create-en-check-opzet, met routeringssignalen en stille verificatie als de onderdelen die niet meekomen
Volgende stappen
- Verificaties versturen: het volledige request- en responsecontract, statussen en limieten
- Landconfiguratie: kanaalvolgorde en beschikbaarheid per land
- Afzenders en branding: hoe elk bericht eruitziet, en de branded e-mailafzender
- Verify events: sessie- en poging-event-payloads
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.