Migrar o Verify do Prelude
Esta página mapeia os API de verificação v2 do Prelude para o Bird Verify. Siga o guia principal de migração na ordem e use estes mapeamentos para os passos 1 e 3.
As estruturas são próximas. POST https://api.prelude.dev/v2/verification e POST /v2/verification/check do Prelude são um par create-and-check com autenticação bearer identificado pelo destinatário em vez de por um ID de verificação, assim como POST /v1/verify/verifications e POST /v1/verify/verifications/check. Chamar create novamente para um destinatário ativo reenvia em vez de iniciar uma nova verificação em ambas as plataformas. O que não é portável é a camada de risco: sinais, vereditos de roteamento e verificação silenciosa do Prelude não têm equivalente na API do Bird Verify.
Passe isso para o seu agente
Cole isso no Claude Code, Cursor ou Codex. O agente percorre esta página no seu repositório, usando a interface Bird que ele já possui: o servidor MCP se estiver conectado, o CLI se estiver instalado e autenticado.
Exemplo de código
I am moving a phone verification integration from Prelude 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/prelude.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 Prelude usage in this repository before you change anything: the /v2/verification and /v2/verification/check call sites, anywhere I read signals or a routing verdict, and anywhere I use dispatch_id for retry safety.
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. Prelude's risk layer does not port either: its signals, its routing verdicts and its silent verification have no counterpart in Bird Verify, so tell me every decision my code makes on those.
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 Prelude cannot be checked by Bird and a code issued by Bird cannot be checked by Prelude. 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 Prelude path is a separate step: ask me again and wait for me to reply with the words retire the Prelude 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.Mapear a chamada create
| O que faz | Prelude | Bird |
|---|---|---|
| Destinatário | target.type + target.value | to.phone_number ou to.email |
| Tamanho do código | options.code_size | options.code_length |
| Preferência de canal | options.preferred_channel, options.channels | options.channels, senão a ordem configurada do país |
| Correlação | metadata.correlation_id | metadata |
| Callbacks de entrega | options.callback_url | um webhook do espaço de trabalho inscrito nos tipos de evento do Verify que você indicar |
| Código personalizado | options.custom_code | sem equivalente |
| Localização | options.locale | options.language |
| Identidade do remetente | options.sender_id | selecione um remetente gerenciado pela Bird ou próprio do espaço de trabalho por canal ou país, não por solicitação |
| Template de mensagem | options.template_id, options.variables | sem equivalente por solicitação; selecione um template de autenticação WhatsApp aprovado na configuração do Verify |
| Preenchimento automático Android | options.app_realm | sem equivalente |
| Sinais de risco | signals (IP, dispositivo, fingerprint) | não aceito |
| Retentativas seguras | sem chave de idempotência ou header na referência de create ou check deles | header Idempotency-Key |
| Correlação de sinais | dispatch_id, "the identifier of the dispatch that came from the front-end SDK" | sem equivalente: Bird não aceita sinais |
| Controle de fallback | options.max_auto_fallbacks, options.force_challenge | o plano de canais do país |
dispatch_id não é um mecanismo de retentativa e não pertence ao lado de Idempotency-Key. A própria referência do Prelude o define como "the identifier of the dispatch that came from the front-end SDK": o SDK do Signals deles o retorna de dispatchSignals(), e você o encaminha no create para que a camada de fraude deles possa associar os sinais do navegador capturados àquela verificação. As referências de create e check deles documentam o conjunto completo de solicitações sem chave de idempotência e sem header personalizado, então um create repetido não é seguro para você. No Bird, o header Idempotency-Key faz isso.
Os conjuntos de canais se sobrepõem apenas parcialmente. Bird entrega por email, SMS, WhatsApp e Telegram; os canais RCS, Viber, Zalo, voz e silenciosos do Prelude não têm equivalente no Bird hoje. Um número que o Prelude alcançava por Viber ou Zalo cai para SMS aqui, o que é uma questão de taxa de entrega que vale medir no piloto em vez de descobrir em volume total.
Mapear a chamada check
Ambos os endpoints de check recebem o destinatário e o código sem ID de verificação, então essa chamada porta quase como está. A resposta é onde eles diferem:
| status do Prelude | Bird |
|---|---|
| success | success: true |
| failure | success: false, reason: incorrect_code |
| expired_or_not_found | success: false, reason: expired ou um 404 |
| (sem valor direto) | success: false, reason: attempts_exhausted |
O Prelude agrupa "wrong code" e "out of attempts" em failure; Bird os separa e retorna attempts_remaining junto para que você possa mostrar ao usuário quantas tentativas restam. Uma verificação que já foi resolvida retorna 404 em vez de um status, então armazene a primeira resposta definitiva em vez de verificar novamente.
O que acontece com a camada de risco
A resposta do create do Prelude reporta um veredito de roteamento: um status de success, retry, challenged, blocked ou shadow_blocked, com um reason e risk_factors quando recusa, e um method nomeando o canal escolhido. A resposta do create de Bird é a própria verificação. Não há veredito para condicionar, nenhum objeto de sinais para enviar e nenhum equivalente de bloqueio sombra, então uma integração que condiciona cadastros ao veredito do Prelude precisa de sua própria decisão antes de chamar Bird.
O que Bird oferece desse espaço é mais restrito e na maior parte configuração: habilitação por país para desligar destinos que você nunca atende, os limites de envio e verificação da plataforma descritos em Proteções contra abuso e o próprio plano de canais. Se a proteção contra pumping foi o motivo pelo qual você escolheu o Prelude, dimensione essa lacuna antes de agendar a migração.
Mover os callbacks
O Prelude envia status de entrega para a callback_url que você define por verificação. Bird entrega para endpoints que o seu espaço de trabalho registra, cada um inscrito nos tipos de evento desejados, então a URL sai do corpo da solicitação. Nomeie os tipos de evento que o seu handler quer: verify.verification.created, verify.verification.verified e verify.verification.failed para a sessão, e verify.attempt.sent, verify.attempt.delivered e verify.attempt.undelivered para cada envio de código de verificação. Não há curinga que substitua todos eles. Verifique assinaturas conforme Standard Webhooks. Os payloads estão em Eventos do Verify.
Virada
A regra de virada no guia principal se aplica sem alteração: um código emitido pelo Prelude não pode ser verificado pelo Bird, então mude na chamada create e direcione cada check para o provedor que emitiu aquela verificação até a última expirar. Como ambas as APIs se baseiam no destinatário, a ramificação é uma única condicional ao redor dos seus call sites existentes em vez de uma reescrita.
Acompanhe a conversão durante o piloto junto com a entrega. O Prelude roteia por solicitação em um conjunto de canais mais amplo; Bird roteia pela ordem de canais que você define por país. Se a conversão de um mercado cair, reordene os canais daquele país antes de concluir qualquer coisa sobre a migração.
Próximos passos
- Enviando verificações: o contrato completo para ambas as chamadas, status e limites
- Configuração por país: ordem de canais e disponibilidade por país
- Remetentes e identidade visual: o que o destinatário vê em cada canal
- Eventos do Verify: os eventos para os quais o seu consumidor de callback migra
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaVerify phone numbers at signupEntenda o conceitoWhat does OTP mean? One-time passwords explainedExplore a funcionalidadeCustomer verificationSiga o percurso de aprendizagemBuild your first integration
Experimente na prática e obtenha um resumo de implementação