Migrare Verify da un altro provider
Usa questa guida per spostare i codici di verifica monouso (OTP) per telefono ed email da un altro provider di verifica a Bird Verify. Il passaggio è contenuto, perché la superficie è contenuta: due chiamate sostituiscono qualsiasi coppia create-and-check del tuo provider attuale, e Bird gestisce il codice, il messaggio e il canale di consegna dietro di esse.
Una differenza strutturale definisce la forma del lavoro. Bird non ha un oggetto service per applicazione né un ID di verifica da tracciare. Una verifica è identificata dal destinatario, quindi entrambe le chiamate ricevono lo stesso to, e lo stato che la tua integrazione deve mantenere si riduce a zero.
Checklist di migrazione:
- Mappa le chiamate create e check
- Configura canali, paesi e mittente
- Porta il ciclo di vita della verifica
- Cambia i webhook
- Passa in produzione una durata di codice alla volta
I passaggi 1 e 3 dipendono dal provider che stai abbandonando. La tua guida al provider contiene la mappatura campo per campo e la traduzione degli stati.
1. Mappa le chiamate create e check
POST /v1/verify/verifications invia un codice di verifica. La richiesta minima è un destinatario:
Esempio di codice
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 invia ciò che l'utente ha digitato, identificato dallo stesso destinatario più il codice. I payload completi sono in Invio delle verifiche.
Quattro differenze da gestire durante il porting:
- Il destinatario è la chiave. I provider che restituiscono un SID o un ID di verifica se lo aspettano nella chiamata check. Bird fa il match sull'insieme di indirizzi, e la corrispondenza deve essere esatta: una verifica creata con email e numero di telefono non viene trovata con uno solo dei due. La colonna che contiene l'ID di verifica del provider può essere eliminata.
- Un codice errato restituisce 200. La risposta contiene success: false, un reason tra incorrect_code, expired o attempts_exhausted, e attempts_remaining. Riserva il percorso di errore ai fallimenti della richiesta. Quando una verifica raggiunge uno stato finale, i check successivi restituiscono 404 anziché success: false.
- Bird genera il codice e non lo restituisce mai. Non esiste un parametro per un codice personalizzato, quindi un'integrazione che forniva il proprio codice di verifica, o lo leggeva dalla risposta per inviarlo autonomamente, non ha un equivalente qui.
- Entrambi gli endpoint accettano Idempotency-Key. Un replay dopo un timeout restituisce la risposta originale senza inviare un altro codice né consumare un tentativo.
Le opzioni per richiesta sono volutamente poche: options.code_length e options.channels, che riordina o restringe i canali per una singola richiesta. Tutto il resto è configurazione dello spazio di lavoro, non un campo sull'invio.
2. Configura canali, paesi e mittente
Bird consegna i codici tramite email, SMS, WhatsApp e Telegram. Per un destinatario telefonico, la maggior parte dei paesi prova prima WhatsApp con SMS come fallback, e la consegna passa al canale successivo nel piano quando un invio fallisce. Imposta l'ordine, o disattiva un canale, per paese nella pagina Countries; disabilita i paesi che non servi, perché una destinazione inutilizzata è esposizione al pumping SMS anziché copertura.
Due lacune da verificare rispetto al flusso attuale prima di fissare una data:
- Non esiste un canale a chiamata vocale né un'autenticazione silenziosa di rete. Un flusso che ricorre a una telefonata per gli utenti che non possono ricevere SMS richiede una soluzione diversa qui.
- Scegli il mittente prima del cutover. Email, SMS e WhatsApp usano per impostazione predefinita Bird Verify e possono usare Authifly in alternativa. Puoi anche utilizzare il tuo dominio email verificato, un Sender ID SMS esistente o un numero WhatsApp collegato con un template di autenticazione approvato. Telegram usa il proprio account di notifica verificato. Se vuoi mantenere un mittente SMS che i tuoi utenti già riconoscono, verifica che sia supportato e registrato in ogni paese di destinazione. Mittenti e branding illustra le opzioni e il comportamento di fallback.
Se usi un tuo numero WhatsApp, seleziona un template di autenticazione approvato esistente nella configurazione di Verify. Bird controlla il testo delle email e dei messaggi SMS. Non puoi passare un ID template o un corpo del messaggio personalizzato in una singola richiesta di verifica.
3. Porta il ciclo di vita della verifica
Una verifica resta pending fino alla risoluzione: verified quando un codice corretto arriva in tempo, failed con motivo attempts_exhausted o undeliverable, oppure expired con motivo ttl_elapsed. Mappa gli stati terminali del tuo provider su questi tre e tratta reason come un enum aperto.
I tempi che modellano la tua UI sono impostazioni dello spazio di lavoro nella pagina Configure: durata di validità del codice, numero di tentativi di check consentiti e durata del cooldown per il reinvio. Impostali in modo che corrispondano all'esperienza attuale dei tuoi utenti, anziché riscrivere i testi della UI. La lunghezza del codice è l'unico valore impostabile anche per singola richiesta. I valori predefiniti e gli intervalli sono in Impostazioni di verifica.
Due comportamenti di solito sostituiscono codice che hai già:
- Il reinvio è di nuovo la chiamata create. Chiama create con lo stesso destinatario: dentro il cooldown restituisce la verifica attiva senza inviare, e dopo il cooldown parte un nuovo codice. Ogni codice inviato per una verifica attiva resta valido fino alla risoluzione della verifica, quindi un utente che inserisce il primo dopo l'arrivo del secondo non viene penalizzato.
- "I didn't get a code" ha un proprio endpoint. POST /v1/verify/verifications/next-channel passa al canale successivo nel piano e invia immediatamente, ignorando il cooldown di reinvio ma mantenendo la scadenza, il budget di tentativi e la verifica. Collegalo al pulsante anziché ripetere i reinvii su un canale che non consegna.
Sopra le tue impostazioni ci sono guardrail della piattaforma che non configuri: un limite orario di invio per indirizzo e un limite di check per destinatario, entrambi restituiti con un 429 e un Retry-After. Se il tuo provider attuale ti permetteva di alzare i limiti per endpoint e lo hai fatto, confronta il tuo picco con i valori in Guardrail anti-abuso prima del passaggio.
4. Cambia i webhook
Verify emette eventi su due assi. Gli eventi di sessione, verify.verification.created, verify.verification.verified e verify.verification.failed, seguono la verifica stessa. Gli eventi di tentativo, verify.attempt.sent, verify.attempt.delivered e verify.attempt.undelivered, seguono ogni singolo invio di codice di verifica: un reinvio o un failover di canale aggiunge tentativi alla stessa sessione. Sottoscrivi un endpoint ai tipi che vuoi con POST /v1/webhooks; i payload sono in Eventi di Verify.
Sottoscrivi gli eventi di sessione necessari alla tua integrazione. verify.verification.failed copre il vicolo cieco della consegna: si attiva con reason: "undeliverable" quando il piano è esaurito e i fallimenti registrati indicano che nessun codice di verifica è stato inviato, e il suo last_attempt_reason riporta l'errore sull'ultimo canale tentato. Una verifica che scade o esaurisce i tentativi di check non emette alcun evento di sessione: prendi questi due esiti dalla risposta del check.
Questi eventi servono per analytics, alerting e strumenti di supporto. La decisione di autenticazione viene dalla chiamata di check, che risponde in modo sincrono, e un flusso di login non dovrebbe mai attendere un webhook per far entrare un utente. La consegna è at-least-once e non ordinata, firmata secondo Standard Webhooks: deduplica sull'header webhook-id come per qualsiasi altro evento Bird.
5. Passare in produzione una durata di codice alla volta
Verify non ha destinatari simulati: quello che vale la pena testare è l'arrivo del codice. Esegui l'integrazione con un numero di telefono e una casella email che controlli, su ogni canale abilitato, prima di toccare la produzione.
Il passaggio in produzione ha una regola facile da dimenticare. Un codice emesso dal vecchio provider non può essere verificato da Bird, e viceversa. Quindi commuta alla chiamata di create e, per la durata di un codice, instrada ogni check al provider che ha emesso quella verifica. In pratica:
- Registra quale provider ha creato ogni verifica in corso.
- Inizia a inviare una quota di nuove verifiche tramite Bird e verifica quelle con Bird.
- Continua a verificare le verifiche più vecchie con il vecchio provider fino alla scadenza dell'ultima, che richiede una finestra di validità del codice più un margine.
- Aumenta la quota di Bird quando i tassi di conversione della prima coorte sono soddisfacenti, poi dismetti il vecchio percorso.
Monitora la conversione, non solo la consegna. La pagina Verifications e le metriche di Verify mostrano invii, consegne e quante verifiche hanno raggiunto verified: è il dato che ti dice se un ordine di canale o una nuova identità mittente ti sta costando registrazioni.
Migrazione da un provider specifico
- Twilio Verify: i Service diventano impostazioni dello spazio di lavoro, VerificationCheck diventa un check identificato dal destinatario, traduzione di canali e stati
- Prelude: una struttura create-and-check quasi identica, con segnali di routing e verifica silenziosa come parti non portabili
Passi successivi
- Invio delle verifiche: contratto completo di request e response, stati e limiti
- Configurazione per paese: ordine dei canali e disponibilità per paese
- Mittenti e branding: aspetto di ogni messaggio e mittente email brandizzato
- Eventi di Verify: payload degli eventi di sessione e di tentativo
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.