Migrar o Verify do Twilio
Esta página mapeia o Twilio Verify v2 para o Bird Verify. Siga o guia principal de migração na ordem indicada e use estes mapeamentos nos passos 1 e 3.
O Service é a peça sem equivalente. O Twilio endereça POST https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications, e o Service contém tamanho do código, TTL, lookup, tratamento de linha fixa e limites de requisições. Bird endereça POST /v1/verify/verifications sem segmento de service: essas configurações pertencem ao seu espaço de trabalho em vez de um ID no path. Múltiplos Service IDs não têm equivalente dentro de um espaço de trabalho, e você não pode selecionar uma configuração por requisição.
Entregue isto ao seu agente
Cole isto no Claude Code, Cursor ou Codex. O agente trabalha com esta página no seu repositório, usando qualquer superfície Bird que ele já tenha: o servidor MCP se houver um conectado, o CLI se estiver instalado e autenticado.
Exemplo de código
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.Mapeie a chamada de criação
| O que faz | Twilio Verify | Bird |
|---|---|---|
| Destinatário | To | to.phone_number ou to.email |
| Canal | Channel | options.channels, senão a ordem configurada do país |
| Tamanho do código | Service CodeLength | options.code_length, senão o padrão do espaço de trabalho |
| Validade do código | Service TTL | a configuração Duration do espaço de trabalho |
| Limite de tentativas | Service max attempts | a configuração Maximum Retries do espaço de trabalho |
| Correlação | Tags | metadata |
| Retentativas seguras | (nenhum) | header Idempotency-Key |
| Código personalizado | CustomCode | sem equivalente |
| Localização | Locale | options.language |
| Conteúdo da mensagem | TemplateSid, CustomFriendlyName, ChannelConfiguration | sem equivalente por requisição; selecione um template de autenticação WhatsApp aprovado na configuração do Verify |
| Throttles por chave | RateLimits | limites fixos da plataforma |
| Controles de fraude | RiskCheck, Fraud Guard, DeviceIp | não exposto na API |
| Preenchimento automático SMS | AppHash | sem equivalente |
| PSD2 | Amount, Payee | sem equivalente |
Os canais também não se correspondem um a um:
| Twilio Channel | Bird |
|---|---|
| sms | sms |
| call | sem equivalente |
| sna, auto | sem equivalente |
| rcs | sem equivalente |
| (nenhum) | telegram, disponível para números registrados no Telegram |
Um fluxo que usa call como fallback de acessibilidade, ou sna e auto para um caminho sem código, precisa ser repensado antes de você se comprometer com uma data. Todo o restante é uma mudança de ordem de canal na página Countries em vez de um parâmetro por requisição.
Mapeie a chamada de verificação
O POST /v2/Services/{ServiceSid}/VerificationCheck do Twilio recebe To ou VerificationSid, mais Code. O POST /v1/verify/verifications/check do Bird recebe apenas o destinatário e o código, então o caminho via VerificationSid desaparece junto com a coluna em que você o armazenava. Informe exatamente o conjunto de endereços com que você criou a verificação.
O formato do resultado difere no que mais importa:
- O Twilio responde com um campo status; o Bird responde com um booleano. success: true significa verificado. success: false traz um reason de incorrect_code, expired ou attempts_exhausted, mais attempts_remaining, então o número de "how many tries left" que você talvez esteja contando por conta própria volta na resposta.
- Ambos passam a 404 quando a verificação se encerra. O Twilio exclui a verificação quando ela é aprovada, expirada ou esgota as tentativas; o Bird para de aceitar verificações em qualquer estado final. Armazene a primeira resposta definitiva em vez de verificar novamente.
Traduza os status
| Status Twilio | Status Bird | Razão Bird |
|---|---|---|
| pending | pending | nenhuma |
| approved | verified | nenhuma |
| max_attempts_reached | failed | attempts_exhausted |
| expired | expired | ttl_elapsed |
| canceled | sem equivalente: uma verificação não pode ser cancelada |
Não existe endpoint de atualização, então o padrão do Twilio de forçar uma verificação para approved ou canceled a partir do seu backend não tem equivalente. Uma verificação termina quando o usuário a confirma, esgota as tentativas ou deixa expirar.
Migre o fluxo de eventos
O Twilio Verify reporta atividade via Event Streams: um sink mais uma assinatura de eventos de status de verificação, configurada fora da API do Verify. O Bird usa o mesmo mecanismo de webhook de todos os outros canais. Registre um endpoint nos tipos de evento desejados, nomeando cada um: verify.verification.created, verify.verification.verified e verify.verification.failed para eventos de sessão, e verify.attempt.sent, verify.attempt.delivered e verify.attempt.undelivered para entregas individuais de código de verificação. Não existe wildcard que substitua todos eles. Verifique a assinatura conforme o Standard Webhooks. Consulte Verify events.
Os dois eixos importam ao migrar dashboards. Os eventos de status de verificação do Twilio correspondem aos eventos de sessão do Bird, e os eventos de tentativa do Bird adicionam resultados de entrega por envio na mesma sessão, incluindo os envios que um reenvio ou failover de canal produz.
Transição
A regra de transição no guia principal é o ponto central do planejamento: um código emitido pelo Twilio não pode ser verificado pelo Bird, então faça a troca na chamada de criação e continue roteando verificações para o provedor que emitiu a verificação até que o último código do Twilio expire.
Verifique o remetente antes da migração. Você pode escolher Bird Verify ou Authifly, usar seu domínio de e-mail verificado, selecionar um SMS Sender ID existente ou vincular seu número WhatsApp conectado a um template de autenticação aprovado. Bird não escolhe entre um pool de remetentes. Se você mantiver um SMS Sender ID como padrão da configuração, o Verify recorre ao Bird Verify apenas onde esse ID não é elegível para o destino; uma escolha explícita de país não faz isso. Confirme o que os usuários veem em cada país e atualize os scripts de suporte onde houver mudança.
Próximos passos
- Envio de verificações: o contrato completo das duas chamadas, status e limites
- Configuração por país: onde a ordem e a disponibilidade de canais agora ficam
- Remetentes e identidade visual: o que o destinatário vê em cada canal
- Eventos do Verify: os eventos para os quais seu consumidor de Event Streams 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