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:
- Petakan panggilan create dan check
- Atur channel, negara, dan pengirim Anda
- Pindahkan lifecycle verifikasi
- Alihkan webhook
- Lakukan cutover satu masa berlaku kode per tahap
Langkah 1 dan 3 bergantung pada penyedia yang Anda tinggalkan. Panduan penyedia Anda memuat pemetaan field-by-field dan terjemahan status.
1. Petakan panggilan create dan check
POST /v1/verify/verifications mengirimkan kode verifikasi. Request paling sederhana adalah satu penerima:
Contoh kode
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 mengirimkan apa yang diketik pengguna, diidentifikasi berdasarkan penerima yang sama ditambah kode. Payload lengkapnya ada di Mengirim verifikasi.
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; 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 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: 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.
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 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 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; payload-nya ada di Event Verify.
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, 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:
- Catat provider mana yang membuat setiap verifikasi yang sedang berjalan.
- Mulai kirimkan sebagian verifikasi baru melalui Bird, dan periksa verifikasi tersebut terhadap Bird.
- Terus periksa verifikasi lama terhadap provider lama sampai yang terakhir kedaluwarsa, yang memakan waktu satu jendela validitas kode ditambah margin.
- Naikkan porsi Bird setelah rasio konversi untuk kohort pertama terlihat baik, lalu hentikan jalur lama.
Pantau konversi, bukan hanya pengiriman. Halaman 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: Services menjadi pengaturan workspace, VerificationCheck menjadi check berbasis penerima, translasi channel dan status
- Prelude: bentuk create-and-check yang hampir identik, dengan sinyal routing dan verifikasi senyap sebagai bagian yang tidak dapat diportasi
Langkah selanjutnya
- Mengirim verifikasi: kontrak request dan response lengkap, status, dan batas
- Konfigurasi negara: urutan channel dan ketersediaan per negara
- Pengirim dan branding: tampilan setiap pesan, dan pengirim email bermerek
- Event Verify: payload event sesi dan percobaan
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.