Migrasi Verify dari Prelude
Halaman ini memetakan API verifikasi v2 Prelude ke Bird Verify. Ikuti panduan migrasi utama secara berurutan dan gunakan pemetaan ini untuk langkah 1 dan 3.
Strukturnya mirip. POST https://api.prelude.dev/v2/verification dan POST /v2/verification/check Prelude adalah pasangan create-and-check dengan autentikasi bearer yang dikunci berdasarkan target, bukan berdasarkan verification ID, begitu juga POST /v1/verify/verifications dan POST /v1/verify/verifications/check. Memanggil create lagi untuk penerima yang masih aktif akan mencoba lagi alih-alih memulai verifikasi baru di kedua platform. Yang tidak dapat dipindahkan adalah lapisan risiko: signals, routing verdict, dan silent verification Prelude tidak memiliki padanan di Bird Verify API.
Serahkan ini ke agent Anda
Tempelkan ini ke Claude Code, Cursor, atau Codex. Agent akan mengerjakan halaman ini terhadap repositori Anda sendiri, menggunakan permukaan Bird mana pun yang sudah tersedia: server MCP jika sudah terhubung, CLI jika sudah terinstal dan masuk.
Contoh kode
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.Petakan panggilan create
| Fungsi | Prelude | Bird |
|---|---|---|
| Penerima | target.type + target.value | to.phone_number atau to.email |
| Panjang kode | options.code_size | options.code_length |
| Preferensi channel | options.preferred_channel, options.channels | options.channels, jika tidak mengikuti urutan yang dikonfigurasi per negara |
| Korelasi | metadata.correlation_id | metadata |
| Callback pengiriman | options.callback_url | webhook workspace yang berlangganan tipe event verify yang Anda tentukan |
| Kode verifikasi kustom | options.custom_code | tidak ada padanan |
| Lokalisasi | options.locale | options.language |
| Identitas pengirim | options.sender_id | pilih pengirim yang dikelola Bird atau dimiliki workspace per kanal atau negara, bukan per permintaan |
| Template pesan | options.template_id, options.variables | tidak ada padanan per permintaan; pilih template autentikasi WhatsApp yang sudah disetujui di konfigurasi Verify |
| Autofill Android | options.app_realm | tidak ada padanan |
| Sinyal risiko | signals (IP, device, fingerprint) | tidak diterima |
| Retry yang aman | tidak ada idempotency key atau header pada referensi create atau check mereka | header Idempotency-Key |
| Korelasi signals | dispatch_id, "the identifier of the dispatch that came from the front-end SDK" | tidak ada padanan: Bird tidak menerima sinyal |
| Kontrol fallback | options.max_auto_fallbacks, options.force_challenge | rencana kanal per negara |
dispatch_id bukan mekanisme retry dan tidak termasuk bersama Idempotency-Key. Referensi Prelude sendiri mendefinisikannya sebagai "the identifier of the dispatch that came from the front-end SDK": SDK Signals mereka mengembalikannya dari dispatchSignals(), dan Anda meneruskannya pada create agar lapisan fraud mereka dapat mencocokkan sinyal browser yang ditangkap dengan verifikasi tersebut. Referensi create dan check mereka mendokumentasikan seluruh set permintaan tanpa idempotency key dan tanpa custom header, sehingga create yang di-retry tidak dibuat aman untuk Anda. Di Bird, header Idempotency-Key melakukan itu.
Kumpulan channel hanya sebagian tumpang tindih. Bird mengirim melalui email, SMS, WhatsApp, dan Telegram; channel RCS, Viber, Zalo, voice, dan silent milik Prelude tidak memiliki padanan Bird saat ini. Nomor yang sebelumnya dijangkau Prelude melalui Viber atau Zalo akan kembali ke SMS di sini, dan ini adalah pertanyaan tingkat pengiriman yang perlu diukur dalam pilot, bukan ditemukan saat volume penuh.
Petakan panggilan check
Kedua endpoint check menerima penerima dan kode tanpa verification ID, jadi panggilan ini dapat dipindahkan hampir apa adanya. Perbedaannya ada pada respons:
| Prelude status | Bird |
|---|---|
| success | success: true |
| failure | success: false, reason: incorrect_code |
| expired_or_not_found | success: false, reason: expired, atau 404 |
| (tidak ada nilai langsung) | success: false, reason: attempts_exhausted |
Prelude menggabungkan "wrong code" dan "out of attempts" ke dalam failure; Bird memisahkannya, dan mengembalikan attempts_remaining di sampingnya agar Anda dapat menunjukkan kepada pengguna berapa percobaan tersisa. Verifikasi yang sudah terselesaikan mengembalikan 404 alih-alih status, jadi simpan jawaban definitif pertama alih-alih memeriksa ulang.
Apa yang terjadi pada lapisan risiko
Respons create Prelude melaporkan routing verdict: status berupa success, retry, challenged, blocked, atau shadow_blocked, dengan reason dan risk_factors saat menolak, dan method yang menyebutkan channel yang dipilih. Respons create Bird adalah verifikasi itu sendiri. Tidak ada verdict untuk dijadikan cabang, tidak ada objek signals untuk dikirim, dan tidak ada padanan shadow block, sehingga integrasi yang menggantungkan pendaftaran pada verdict Prelude memerlukan keputusan sendiri sebelum memanggil Bird.
Yang dibawa Bird dari ranah itu lebih sempit dan sebagian besar berupa konfigurasi: pengaktifan per negara untuk menonaktifkan destinasi yang tidak pernah Anda layani, batas pengiriman dan pengecekan platform yang dijelaskan dalam Perlindungan penyalahgunaan, dan channel plan itu sendiri. Jika perlindungan terhadap pumping adalah alasan Anda memilih Prelude, ukur celah tersebut sebelum menjadwalkan perpindahan.
Pindahkan callback
Prelude mengirimkan status pengiriman ke callback_url yang Anda tetapkan per verifikasi. Bird mengirimkan ke endpoint yang didaftarkan workspace Anda, masing-masing berlangganan tipe event yang diinginkan, sehingga URL keluar dari body permintaan. Tentukan tipe event yang diinginkan handler Anda: verify.verification.created, verify.verification.verified dan verify.verification.failed untuk sesi, dan verify.attempt.sent, verify.attempt.delivered dan verify.attempt.undelivered untuk setiap pengiriman kode verifikasi. Tidak ada wildcard yang menggantikan semuanya. Verifikasi tanda tangan sesuai Standard Webhooks. Payload-nya ada di Verify events.
Peralihan
Aturan peralihan dalam panduan utama berlaku tanpa perubahan: kode yang diterbitkan Prelude tidak dapat diperiksa oleh Bird, jadi alihkan pada panggilan create dan arahkan setiap check ke provider mana pun yang menerbitkan verifikasi tersebut sampai yang terakhir kedaluwarsa. Karena kedua API dikunci berdasarkan penerima, percabangannya berupa satu kondisional di sekitar call site Anda yang sudah ada, bukan penulisan ulang.
Pantau konversi selama pilot bersamaan dengan pengiriman. Prelude merutekan per permintaan melalui kumpulan channel yang lebih luas; Bird merutekan berdasarkan urutan channel yang Anda tetapkan per negara. Jika konversi suatu pasar menurun, ubah urutan channel negara tersebut sebelum menyimpulkan apa pun tentang perpindahan.
Langkah selanjutnya
- Mengirim verifikasi: kontrak lengkap untuk kedua panggilan, status, dan batas
- Konfigurasi negara: urutan channel dan ketersediaan per negara
- Pengirim dan branding: apa yang dilihat penerima di setiap channel
- Verify events: event yang menjadi tujuan perpindahan konsumer callback Anda
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.