# Migrasi Verify dari Prelude

Halaman ini memetakan API verifikasi v2 Prelude ke Bird Verify. Ikuti [panduan migrasi utama](/docs/guides/verify/migrate) 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`](/docs/api/reference/create-verification) dan [`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-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.

```text
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`](/docs/guides/idempotency) 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](/docs/guides/verify/sending-verifications#abuse-guardrails), 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](https://www.standardwebhooks.com). Payload-nya ada di [Verify events](/docs/guides/verify/events).

## Peralihan

[Aturan peralihan](/docs/guides/verify/migrate#5-cut-over-one-code-lifetime-at-a-time) 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](/docs/guides/verify/sending-verifications): kontrak lengkap untuk kedua panggilan, status, dan batas
- [Konfigurasi negara](/docs/guides/verify/countries): urutan channel dan ketersediaan per negara
- [Pengirim dan branding](/docs/guides/verify/senders): apa yang dilihat penerima di setiap channel
- [Verify events](/docs/guides/verify/events): event yang menjadi tujuan perpindahan konsumer callback Anda

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)