Migrare Verify da Twilio
Questa pagina mappa Twilio Verify v2 su Bird Verify. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 1 e 3.
Il Service è l'elemento senza corrispondente. Twilio indirizza POST https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications, e il Service contiene lunghezza del codice, TTL, lookup, gestione delle linee fisse e limiti di frequenza. Bird indirizza POST /v1/verify/verifications senza segmento service: queste impostazioni appartengono al tuo spazio di lavoro anziché a un ID nel path. Più Service ID non hanno equivalente all'interno di uno spazio di lavoro, e non puoi selezionare una configurazione per singola richiesta.
Passa questo al tuo agente
Incolla questo in Claude Code, Cursor o Codex. L'agente lavora su questa pagina confrontandola con il tuo repository, usando qualsiasi superficie Bird già disponibile: il server MCP se connesso, o CLI se installato e autenticato.
Esempio di codice
I am moving a phone verification integration from Twilio Verify to Bird Verify. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/verify/migrate/twilio.md for the create, check and status mapping, and https://bird.com/docs/guides/verify/migrate.md for the order the steps go in.
3. Find and list my Twilio Verify usage in this repository before you change anything: the Verifications and VerificationCheck call sites, every Service SID they name and what each Service is configured with, and any place I read a verification status. Bird has no Service segment and no per-request configuration selection, so tell me if I use more than one Service and what differs between them.
4. Tell me early which of these I depend on. Bird Verify has no voice channel and no silent or network-based authentication. It generates the code itself and never returns it, so I cannot supply my own. It accepts `options.language` but no per-request template or message body. Bird can use an existing SMS Sender ID or a connected WhatsApp number with an approved authentication template, configured per channel or country rather than per request; tell me whether my current sender can be kept. Twilio's Service holds code length, TTL, lookup, landline handling and rate limits; on Bird those belong to the workspace rather than to an ID in the path, so tell me which of my Service settings have no home.
5. Configure my channels and destinations following https://bird.com/docs/guides/verify/countries.md and https://bird.com/docs/guides/verify/senders.md. While you are there, disable every country I do not actually verify into. An enabled destination I never send to is not reach, it is exposure to SMS pumping, so ask me which countries I serve rather than leaving the defaults.
6. Port the create and check calls using the mapping tables on the provider page, and move my status handling to Bird's events: https://bird.com/docs/guides/verify/sending-verifications.md and https://bird.com/docs/guides/verify/events.md.
7. Cut over at the create call, not all at once, because a code issued by Twilio Verify cannot be checked by Bird and a code issued by Bird cannot be checked by Twilio Verify. From the moment I say go, send every NEW verification to Bird, and keep routing each check to whichever provider issued that verification. Keep both paths live for one full code lifetime plus margin, then retire the old one. Tell me how you will decide which provider issued a given verification before you write any of it.
8. Test before any real traffic. Bird Verify has no simulated recipients, so do not look for a sandbox: the thing worth testing is the code arriving. Run the integration against a phone number and a mailbox I control, on each channel I enabled, and show me what arrived on each one.
9. Stop and ask me wherever a step needs a decision. Do not start routing new verifications to Bird until I have seen those test results and replied with the words cut over to Bird. Retiring the Twilio Verify path is a separate step: ask me again and wait for me to reply with the words retire the Twilio Verify path, and do not retire it while any code it issued could still be checked. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.Mappa la chiamata di creazione
| Funzione | Twilio Verify | Bird |
|---|---|---|
| Destinatario | To | to.phone_number o to.email |
| Canale | Channel | options.channels, altrimenti l'ordine configurato per il paese |
| Lunghezza codice | Service CodeLength | options.code_length, altrimenti il valore predefinito dello spazio di lavoro |
| Durata del codice | Service TTL | l'impostazione Duration dello spazio di lavoro |
| Limite di tentativi | Service max attempts | l'impostazione Maximum Retries dello spazio di lavoro |
| Correlazione | Tags | metadata |
| Ritentativi sicuri | (nessuno) | header Idempotency-Key |
| Codice personalizzato | CustomCode | nessun equivalente |
| Localizzazione | Locale | options.language |
| Contenuto del messaggio | TemplateSid, CustomFriendlyName, ChannelConfiguration | nessun equivalente per singola richiesta; seleziona un template di autenticazione WhatsApp approvato nella configurazione di Verify |
| Throttle per chiave | RateLimits | limiti fissi della piattaforma |
| Controlli antifrode | RiskCheck, Fraud Guard, DeviceIp | non esposto sulla API |
| Autocompletamento SMS | AppHash | nessun equivalente |
| PSD2 | Amount, Payee | nessun equivalente |
Neanche i canali hanno una corrispondenza uno a uno:
| Twilio Channel | Bird |
|---|---|
| sms | sms |
| call | nessun equivalente |
| sna, auto | nessun equivalente |
| rcs | nessun equivalente |
| (nessuno) | telegram, disponibile per numeri registrati con Telegram |
Un flusso che usa call come fallback di accessibilità, o sna e auto per un percorso senza codice, va ripensato prima di fissare una data. Tutto il resto è una modifica dell'ordine dei canali nella pagina Countries anziché un parametro per richiesta.
Mappa la chiamata di verifica
La POST /v2/Services/{ServiceSid}/VerificationCheck di Twilio accetta To o VerificationSid, più Code. La POST /v1/verify/verifications/check di Bird accetta solo il destinatario e il codice, quindi il path VerificationSid scompare insieme alla colonna in cui lo memorizzavi. Fornisci esattamente lo stesso set di indirizzi con cui hai creato la verifica.
La struttura della risposta differisce dove conta di più:
- Twilio risponde con un campo status; Bird risponde con un booleano. success: true significa verificato. success: false contiene un reason con valore incorrect_code, expired o attempts_exhausted, più attempts_remaining, quindi il conteggio "how many tries left" che potresti star calcolando lato tuo viene restituito nella risposta.
- Entrambi passano a 404 una volta che la verifica è esaurita. Twilio elimina la verifica quando è approvata, scaduta o ha esaurito i tentativi; Bird smette di accettare controlli in qualsiasi stato finale. Salva la prima risposta definitiva anziché ricontrollare.
Tradurre gli stati
| Stato Twilio | Stato Bird | Motivo Bird |
|---|---|---|
| pending | pending | nessuno |
| approved | verified | nessuno |
| max_attempts_reached | failed | attempts_exhausted |
| expired | expired | ttl_elapsed |
| canceled | nessun equivalente: una verifica non è cancellabile |
Non esiste un endpoint di aggiornamento, quindi il pattern Twilio di forzare una verifica a approved o canceled dal tuo backend non ha corrispondente. Una verifica termina quando l'utente la completa, esaurisce i tentativi o la lascia scadere.
Spostare il flusso di eventi
Twilio Verify segnala l'attività tramite Event Streams: un sink più una sottoscrizione agli eventi di stato delle verifiche, configurata al di fuori della API di Verify. Bird usa lo stesso meccanismo webhook di ogni altro canale. Sottoscrivi un endpoint ai tipi di evento che ti servono, indicandoli uno per uno: verify.verification.created, verify.verification.verified e verify.verification.failed per gli eventi di sessione, e verify.attempt.sent, verify.attempt.delivered e verify.attempt.undelivered per le singole consegne dei codici. Non esiste un carattere jolly che li sostituisca. Verifica la firma secondo Standard Webhooks. Vedi eventi di Verify.
I due assi contano quando porti le dashboard. Gli eventi di stato delle verifiche di Twilio corrispondono agli eventi di sessione di Bird, e gli eventi di tentativo di Bird aggiungono gli esiti di consegna per singolo invio sulla stessa sessione, inclusi gli invii prodotti da un reinvio o da un failover di canale.
Cutover
La regola di cutover nella guida principale è quella attorno a cui pianificare: un codice emesso da Twilio non può essere verificato da Bird, quindi esegui lo switch alla chiamata di creazione e continua a instradare i controlli verso il provider che ha emesso la verifica, fino alla scadenza dell'ultimo codice Twilio.
Controlla il mittente prima del cutover. Puoi scegliere Bird Verify o Authifly, usare il tuo dominio email verificato, selezionare un Sender ID SMS esistente oppure associare il tuo numero WhatsApp connesso a un template di autenticazione approvato. Bird non seleziona tra un pool di mittenti. Se mantieni un Sender ID SMS come impostazione predefinita della configurazione, Verify ricade su Bird Verify solo dove quell'ID non è idoneo per la destinazione; una scelta esplicita del paese no. Verifica ciò che gli utenti vedono in ogni paese e aggiorna gli script di supporto dove cambia.
Passaggi successivi
- Invio delle verifiche: il contratto completo per entrambe le chiamate, stati e limiti
- Configurazione per paese: dove risiedono ora l'ordine e la disponibilità dei canali
- Mittenti e branding: cosa vede il destinatario su ciascun canale
- Eventi di Verify: gli eventi verso cui spostare il tuo consumer di Event Streams
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.