# Migrasi Verify dari penyedia lain

Gunakan panduan ini untuk memindahkan kode verifikasi sekali pakai (OTP) melalui telepon dan email dari penyedia verifikasi lain ke Bird Verify. Proses migrasinya kecil, karena permukaannya kecil: dua panggilan menggantikan pasangan create-and-check penyedia Anda saat ini, dan Bird mengelola kode, pesan, serta channel pengiriman di baliknya.

Satu perbedaan struktural menentukan bentuk pekerjaan ini. Bird tidak memiliki objek service per aplikasi dan tidak ada verification ID yang perlu Anda lacak. Verifikasi diidentifikasi berdasarkan penerimanya, sehingga kedua panggilan menggunakan `to` yang sama, dan state yang perlu disimpan integrasi Anda menyusut menjadi nol.

Daftar langkah migrasi:

1. [Petakan panggilan create dan check](#1-petakan-panggilan-create-dan-check)
2. [Atur channel, negara, dan pengirim Anda](#2-atur-channel-negara-dan-pengirim-anda)
3. [Pindahkan lifecycle verifikasi](#3-pindahkan-lifecycle-verifikasi)
4. [Alihkan webhook](#4-alihkan-webhook)
5. [Lakukan cutover satu masa berlaku kode per tahap](#5-beralih-satu-masa-berlaku-kode-pada-satu-waktu)

Langkah 1 dan 3 bergantung pada penyedia yang Anda tinggalkan. [Panduan penyedia](#migrasi-dari-provider-tertentu) Anda memuat pemetaan field-by-field dan terjemahan status.

## 1. Petakan panggilan create dan check

[`POST /v1/verify/verifications`](/docs/api/reference/create-verification) mengirimkan kode verifikasi. Request paling sederhana adalah satu penerima:

```bash
curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"phone_number": "+15551234567"}}'
```

[`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check) mengirimkan apa yang diketik pengguna, diidentifikasi berdasarkan penerima yang sama ditambah kode. Payload lengkapnya ada di [Mengirim verifikasi](/docs/guides/verify/sending-verifications).

Empat perbedaan yang perlu ditangani saat migrasi:

- **Penerima adalah kuncinya.** Penyedia yang mengembalikan verification SID atau ID mengharuskan nilai itu dikirim kembali saat check. Bird mencocokkan berdasarkan kumpulan alamat, dan harus cocok persis: verifikasi yang dibuat dengan email dan nomor telepon sekaligus tidak ditemukan jika hanya salah satu yang dikirim. Kolom apa pun yang menyimpan verification ID penyedia dapat dihapus.
- **Kode yang salah mengembalikan `200`.** Respons memuat `success: false`, sebuah `reason` berupa `incorrect_code`, `expired`, atau `attempts_exhausted`, dan `attempts_remaining`. Cadangkan jalur error Anda untuk kegagalan request. Setelah verifikasi mencapai state akhir, check berikutnya mengembalikan `404` alih-alih `success: false`.
- **Bird menghasilkan kode dan tidak pernah mengembalikannya.** Tidak ada parameter custom-code, sehingga integrasi penyedia yang menyediakan kode verifikasi sendiri, atau membaca kode kembali untuk mengirimnya sendiri, tidak memiliki padanan di sini.
- **Kedua endpoint menerima `Idempotency-Key`.** Replay setelah timeout mengembalikan respons asli tanpa mengirim kode lagi atau menghabiskan satu percobaan.

Opsi per-request sengaja dibuat sedikit: `options.code_length` dan `options.channels`, yang mengurutkan ulang atau mempersempit channel untuk satu request. Semua hal lainnya adalah konfigurasi workspace, bukan field pada pengiriman.

## 2. Atur channel, negara, dan pengirim Anda

Bird mengirimkan kode melalui email, SMS, WhatsApp, dan Telegram. Untuk penerima telepon, sebagian besar negara mencoba WhatsApp terlebih dahulu dengan SMS sebagai fallback, dan pengiriman berpindah ke channel berikutnya dalam rencana jika pengiriman gagal. Atur urutannya, atau nonaktifkan sebuah channel, per negara di halaman [**Countries**](https://bird.com/dashboard/w/verify/countries); nonaktifkan negara yang tidak Anda layani selagi di sana, karena tujuan yang tidak digunakan adalah paparan terhadap pemompaan SMS, bukan jangkauan.

Dua celah yang perlu diperiksa terhadap alur Anda saat ini sebelum Anda menetapkan tanggal:

- **Tidak ada channel panggilan suara dan tidak ada autentikasi jaringan senyap.** Alur yang melakukan fallback ke panggilan telepon untuk pengguna yang tidak dapat menerima SMS memerlukan solusi lain di sini.
- **Pilih pengirim sebelum cutover.** Email, SMS, dan WhatsApp secara default menggunakan Bird Verify dan dapat menggunakan Authifly sebagai gantinya. Anda juga dapat menggunakan domain email terverifikasi Anda, Sender ID SMS yang sudah ada, atau nomor WhatsApp yang terhubung dengan template autentikasi yang telah disetujui. Telegram menggunakan akun notifikasi terverifikasinya sendiri. Jika Anda ingin mempertahankan pengirim SMS yang sudah dikenali pengguna Anda, pastikan pengirim tersebut didukung dan terdaftar di setiap negara tujuan. [Pengirim dan branding](/docs/guides/verify/senders) membahas pilihan dan perilaku fallback.

Jika Anda menggunakan nomor WhatsApp sendiri, pilih template autentikasi yang telah disetujui di konfigurasi Verify Anda. Bird mengontrol salinan pesan email dan SMS. Anda tidak dapat mengirimkan template ID atau isi pesan kustom pada permintaan verifikasi individual.

## 3. Pindahkan lifecycle verifikasi

Sebuah verifikasi berstatus `pending` sampai terselesaikan: `verified` ketika kode yang benar tiba tepat waktu, `failed` dengan alasan `attempts_exhausted` atau `undeliverable`, atau `expired` dengan alasan `ttl_elapsed`. Petakan status akhir provider Anda ke tiga status tersebut, dan perlakukan `reason` sebagai open enum.

Pengaturan waktu yang membentuk UI Anda adalah pengaturan workspace di halaman [**Configure**](https://bird.com/dashboard/w/verify/configure): berapa lama kode tetap valid, berapa kali percobaan check yang didapat pengguna, dan berapa lama cooldown pengiriman ulang berjalan. Atur nilainya agar sesuai dengan pengalaman pengguna Anda saat ini, alih-alih menulis ulang teks UI Anda. Panjang kode adalah satu-satunya nilai yang juga dapat diatur per request. Default dan rentangnya ada di [Pengaturan verifikasi](/docs/guides/verify/sending-verifications#verification-settings).

Dua perilaku yang biasanya menggantikan kode yang sudah Anda miliki:

- **Pengiriman ulang adalah panggilan create lagi.** Panggil create dengan penerima yang sama: di dalam cooldown, panggilan ini mengembalikan verifikasi aktif tanpa mengirim, dan setelahnya kode baru dikirim. Setiap kode yang dikirim untuk verifikasi aktif tetap valid hingga verifikasi terselesaikan, sehingga pengguna yang memasukkan kode pertama setelah kode kedua tiba tidak dirugikan.
- **"I didn't get a code" memiliki endpoint tersendiri.** [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) berpindah ke channel berikutnya dalam rencana dan langsung mengirim di sana, mengabaikan cooldown pengiriman ulang tetapi mempertahankan kedaluwarsa, anggaran percobaan, dan verifikasi. Hubungkan ke tombol alih-alih mengulang pengiriman di channel yang tidak sampai.

Di atas pengaturan Anda terdapat guardrail platform yang tidak Anda konfigurasi: batas pengiriman per alamat per jam dan batas check per penerima, keduanya dijawab dengan `429` dan `Retry-After`. Jika penyedia Anda saat ini mengizinkan Anda menaikkan batas laju per endpoint dan Anda melakukannya, periksa puncak Anda terhadap angka di [Guardrail penyalahgunaan](/docs/guides/verify/sending-verifications#abuse-guardrails) sebelum cutover.

## 4. Alihkan webhook

Verify mengirimkan event pada dua sumbu. Event sesi, `verify.verification.created`, `verify.verification.verified`, dan `verify.verification.failed`, mengikuti verifikasi itu sendiri. Event percobaan, `verify.attempt.sent`, `verify.attempt.delivered`, dan `verify.attempt.undelivered`, mengikuti setiap pengiriman kode verifikasi individual, sehingga pengiriman ulang atau failover channel menambahkan percobaan ke sesi yang sama. Daftarkan endpoint ke tipe yang Anda inginkan dengan [`POST /v1/webhooks`](/docs/api/reference/create-webhook); payload-nya ada di [Event Verify](/docs/guides/verify/events).

Daftarkan event sesi yang dibutuhkan integrasi Anda. `verify.verification.failed` mencakup jalan buntu pengiriman: event ini aktif dengan `reason: "undeliverable"` ketika rencana sudah habis dan kegagalan yang tercatat menunjukkan bahwa tidak ada kode verifikasi yang terkirim, dan `last_attempt_reason`-nya menyebutkan kegagalan pada channel terakhir yang dicoba. Verifikasi yang kedaluwarsa atau kehabisan percobaan check tidak mengirimkan event sesi, jadi ambil kedua hasil tersebut dari respons check.

Event-event ini melayani analitik, alerting, dan tooling dukungan. Keputusan autentikasi Anda berasal dari panggilan check, yang menjawab secara sinkron, dan alur login tidak boleh menunggu webhook untuk mengizinkan pengguna masuk. Pengiriman bersifat at-least-once dan tidak berurutan, ditandatangani sesuai [Standard Webhooks](https://www.standardwebhooks.com), jadi deduplikasi berdasarkan header `webhook-id` dengan cara yang sama seperti setiap event Bird lainnya.

## 5. Beralih satu masa berlaku kode pada satu waktu

Verify tidak memiliki penerima simulasi: yang perlu diuji adalah kode yang tiba, jadi jalankan integrasi terhadap nomor telepon dan kotak masuk yang Anda kontrol, di setiap channel yang Anda aktifkan, sebelum menyentuh produksi.

Peralihan itu sendiri punya satu aturan yang mudah terlewat. **Kode yang diterbitkan oleh provider lama Anda tidak bisa diperiksa oleh Bird, dan sebaliknya.** Jadi beralihlah pada panggilan create, dan selama satu masa berlaku kode, arahkan setiap check ke provider mana pun yang menerbitkan verifikasi tersebut. Dalam praktiknya:

1. Catat provider mana yang membuat setiap verifikasi yang sedang berjalan.
2. Mulai kirimkan sebagian verifikasi baru melalui Bird, dan periksa verifikasi tersebut terhadap Bird.
3. Terus periksa verifikasi lama terhadap provider lama sampai yang terakhir kedaluwarsa, yang memakan waktu satu jendela validitas kode ditambah margin.
4. Naikkan porsi Bird setelah rasio konversi untuk kohort pertama terlihat baik, lalu hentikan jalur lama.

Pantau konversi, bukan hanya pengiriman. Halaman [**Verifications**](https://bird.com/dashboard/w/verify/verifications) dan metrik Verify menampilkan pengiriman, penerimaan, dan berapa banyak verifikasi yang mencapai `verified`, yaitu angka yang memberi tahu Anda apakah urutan channel atau identitas pengirim baru mengurangi pendaftaran Anda.

## Migrasi dari provider tertentu

- [Twilio Verify](/docs/guides/verify/migrate/twilio): Services menjadi pengaturan workspace, `VerificationCheck` menjadi check berbasis penerima, translasi channel dan status
- [Prelude](/docs/guides/verify/migrate/prelude): bentuk create-and-check yang hampir identik, dengan sinyal routing dan verifikasi senyap sebagai bagian yang tidak dapat diportasi

## Langkah selanjutnya

- [Mengirim verifikasi](/docs/guides/verify/sending-verifications): kontrak request dan response lengkap, status, dan batas
- [Konfigurasi negara](/docs/guides/verify/countries): urutan channel dan ketersediaan per negara
- [Pengirim dan branding](/docs/guides/verify/senders): tampilan setiap pesan, dan pengirim email bermerek
- [Event Verify](/docs/guides/verify/events): payload event sesi dan percobaan

## 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)