Mengirim verifikasi

Memverifikasi pengguna membutuhkan dua panggilan. POST /v1/verify/verifications mengirim kode verifikasi ke alamat email atau nomor telepon. POST /v1/verify/verifications/check mengirimkan nilai yang diketik pengguna dan melaporkan apakah nilainya cocok. Bird membuat kode, tidak mengembalikannya dalam respons API, dan memberlakukan kedaluwarsa serta batas percobaan.

Kirim kode

Permintaan valid terkecil adalah penerima to:

const verification = await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);

verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)

verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();

bird verify verifications create --body-file - <<'JSON'
{
  "to": {
    "phone_number": "+15551234567"
  },
  "metadata": {
    "correlation_id": "signup-7f3a"
  }
}
JSON

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

Gunakan host regional Anda (https://us1.platform.bird.com atau https://eu1.platform.bird.com) dengan kunci bk_{region}_... yang sesuai.

Penerima

to mengidentifikasi penerima dengan email, phone_number dalam format E.164, atau keduanya. Alamat email mengaktifkan pengiriman via email. Nomor telepon diselesaikan ke kanal yang tersedia di negara tujuannya, sesuai urutan yang ditetapkan oleh konfigurasi negara. Sebagian besar negara mencoba WhatsApp sebelum SMS, sementara beberapa mencoba SMS terlebih dahulu; Telegram mengikuti keduanya dalam urutan fallback platform. Jika Anda menyediakan kedua alamat, percobaan yang gagal dapat beralih ke kanal lain yang tersedia.

Opsi

options menimpa pengaturan hanya untuk permintaan ini:

• code_length: panjang kode verifikasi untuk verifikasi ini, 4 sampai 8 digit, menimpa nilai default.
• channels: mengubah urutan atau mempersempit kanal pengiriman untuk permintaan ini. Cantumkan nama kanal (sms, whatsapp, email, telegram) sesuai urutan yang ingin dicoba; kanal yang Anda hilangkan tidak digunakan, dan nama yang tidak ada dalam rencana penerima yang sudah diselesaikan akan diabaikan. Anda tidak bisa menambah kanal dengan cara ini, hanya memangkas atau mengubah urutan dari yang sudah diizinkan oleh penerima dan konfigurasi negara, dan daftar yang tidak menyisakan kanal yang dapat digunakan akan menggagalkan permintaan dengan 422.
• language: tag BCP 47 seperti fr atau pt-BR yang menentukan terjemahan bawaan mana yang digunakan pesan kode. Jika dihilangkan, bahasa mengikuti nomor telepon penerima; lihat Bahasa pesan.

Metadata

metadata adalah objek bebas yang dikembalikan di setiap pembacaan; gunakan untuk membawa ID pengguna atau referensi sesi Anda sendiri. Pilihan pengirim dan pengaturan verifikasi tidak dikirim bersama permintaan: keduanya berasal dari konfigurasi workspace Anda, yang dikelola di dashboard (lihat Pengaturan verifikasi).

Respons

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "phone_number": "+15551234567" },
  "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
  "last_channel": "whatsapp",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

channels adalah rencana pengiriman terurut yang dihasilkan verifikasi ini (penerima telepon mencantumkan kanal teleponnya dalam urutan percobaan), dan last_channel adalah ke mana kode terakhir dikirim. expires_at adalah kapan verifikasi kedaluwarsa jika tidak ada kode yang benar masuk; pengiriman ulang tidak memperpanjangnya.

Bahasa pesan

Pesan SMS, email, dan WhatsApp bersama dari Bird tersedia dalam 40 terjemahan bawaan. Pengirim WhatsApp kustom menggunakan bahasa yang disetujui dari template autentikasi yang dipilihnya. Telegram menulis pesannya sendiri, jadi pengaturan ini tidak berpengaruh di sana.

Tanpa options.language, bahasa diambil dari nomor telepon penerima. Nomor Prancis mendapat bahasa Prancis dan nomor Jepang mendapat bahasa Jepang, tanpa Anda memintanya. Verifikasi tanpa nomor telepon mengirim dalam bahasa Inggris, begitu juga verifikasi yang negaranya tidak memiliki terjemahan.

Atur options.language untuk memilih sendiri, misalnya agar sesuai dengan bahasa yang dipilih pengguna di aplikasi Anda, bukan negara dari nomor mereka:

{
  "to": { "phone_number": "+15551234567" },
  "options": { "language": "es" }
}

Tag yang tidak memiliki terjemahan bawaan akan mundur ke bahasa dasarnya, lalu ke bahasa Inggris: en-GB mengirim dalam bahasa Inggris, pt-BR mengirim dalam bahasa Portugis. Hanya tag yang formatnya salah yang ditolak, dengan 422. Berikut terjemahan bawaan yang dapat Anda minta, semuanya tersedia di SMS dan email, dan semuanya kecuali bahasa Mongolia tersedia di pengirim WhatsApp bersama milik Bird:

Referensi create-verification adalah daftar resmi.

Bahasa ditetapkan saat verifikasi dibuat, sehingga pengiriman ulang atau peralihan ke kanal lain tiba dalam bahasa yang sama dengan pesan pertama. Memanggil create lagi untuk penerima yang sama dengan language yang berbeda akan menggunakan kembali verifikasi yang sedang berlangsung dan tidak mengubahnya.

Terjemahan yang digunakan saat pengiriman bisa berbeda dari tag yang Anda kirim jika terjadi fallback. Buka verifikasi di halaman Verifications untuk memastikannya: setiap percobaan menampilkan bahasa yang dirender sebagai tag Template. Pengirim WhatsApp bersama milik Bird tidak memiliki template bahasa Mongolia (mn), sehingga mengirim dalam bahasa Inggris untuk bahasa tersebut, sementara SMS dan email tetap menggunakan bahasa Mongolia. Template WhatsApp Anda sendiri mengikuti bahasa yang disetujui dan kebijakan bahasanya; bahasa yang tidak dapat dikirim dapat menyebabkan percobaan WhatsApp gagal.

Anda dapat memilih bahasa per permintaan, tetapi tidak dapat menyertakan isi pesan dalam permintaan tersebut. Pengirim WhatsApp kustom menggunakan isi dari template autentikasi yang dipilihnya. Pengirim dan branding menampilkan pilihan pengirim dan teks pesan Bird.

Periksa kode

Kirimkan apa pun yang diketik pengguna ke POST /v1/verify/verifications/check, dengan kunci penerima yang sama; tidak perlu ID verifikasi. Sediakan set to yang sama persis seperti saat Anda membuat verifikasi: verifikasi yang dibuat dengan kedua alamat tidak dapat ditemukan dengan salah satu alamat saja.

const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);

result = client.verify.verifications.check(
    to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)

result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
	To:   bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
	Code: "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*result.Success)

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
        ->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';

bird verify verifications check 123456 --phone-number +15551234567

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" },
    "code": "123456"
  }'

Respons menunjukkan apakah kode cocok:

{
  "success": false,
  "reason": "incorrect_code",
  "attempts_remaining": 4,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "pending",
    "reason": null,
    "to": { "phone_number": "+15551234567" },
    "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
    "last_channel": "whatsapp",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": null,
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:38Z"
  }
}

Tangani dua perilaku respons berikut:

• Kode yang salah mengembalikan 200. Perlakukan success: false dengan reason (incorrect_code, expired, attempts_exhausted) sebagai jawaban normal. attempts_remaining memberi tahu berapa percobaan yang tersisa. Gunakan penanganan error hanya untuk kegagalan permintaan.
• Verifikasi final tidak dapat diperiksa lagi. Setelah verifikasi mencapai status final apa pun, pemeriksaan selanjutnya mengembalikan 404. Simpan hasil definitif pertama alih-alih memeriksa lagi.

Jika pengguna meminta kode baru, panggil endpoint create lagi dengan penerima yang sama: verifikasi yang sedang berlangsung digunakan kembali, bukan diganti. Setelah jeda pengiriman ulang berakhir (60 detik secara default), kode baru dikirimkan; dalam jeda tersebut, panggilan mengembalikan verifikasi aktif tanpa mengirim lagi. Setiap kode yang dikirim untuk verifikasi aktif tetap valid sampai verifikasi selesai atau kedaluwarsa, sehingga pengguna dapat memasukkan kode mana pun yang tiba.

Kirim kode melalui kanal lain

Saat pengguna melaporkan bahwa tidak ada kode yang tiba sama sekali, POST /v1/verify/verifications/next-channel memajukan verifikasi ke kanal berikutnya dalam rencananya dan mengirimkan kode baru ke sana. Ini adalah endpoint di balik tombol "I didn't receive my code": aplikasi Anda memutuskan untuk berpindah kanal alih-alih menunggu sinyal status pengiriman.

Gunakan kunci penerima yang sama seperti saat Anda membuat verifikasi, sama seperti pada pemeriksaan:

const verification = await bird.verify.verifications.nextChannel({
  to: { phone_number: "+15551234567" },
});
console.log(verification.last_channel);

verification = client.verify.verifications.next_channel(
    to={"phone_number": "+15551234567"}
)
print(verification.last_channel)

verification, err := client.Verify.Verifications.NextChannel(context.Background(), bird.VerifyVerificationsNextChannelParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
if verification.LastChannel != nil {
	fmt.Println(*verification.LastChannel)
}

$verification = $bird->verify->verifications->nextChannel(
    (new VerificationNextChannelRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getLastChannel();

bird verify verifications next-channel --phone-number +15551234567

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

Responsnya adalah verifikasi, dengan last_channel menyebutkan kanal tujuan kode baru. Setiap kode yang sudah dikirim tetap valid, sehingga pesan yang tiba terlambat masih dapat diperiksa.

Dua hal yang membedakan ini dari pengiriman ulang:

• Jeda pengiriman ulang tidak berlaku. Peralihan kanal yang disengaja adalah tindakan yang berbeda dari meminta kanal yang sama lagi, sehingga pengiriman langsung keluar.
• Hanya kanal yang maju. Kedaluwarsa, batas percobaan, dan ID verifikasi tetap seperti semula.

Gunakan pengiriman ulang saat pengguna ingin mencoba lagi di kanal yang berfungsi, dan gunakan endpoint ini saat kanal itu sendiri yang tampak bermasalah. Nomor telepon dengan rencana WhatsApp lalu SMS maju ke SMS; penerima dengan hanya satu kanal yang dapat digunakan tidak punya tujuan lain.

Empat respons yang perlu ditangani, bukan sekadar dicoba ulang:

Setiap kode yang dikirim endpoint ini dikenakan tagihan seperti pengiriman Verify lainnya; lihat Biaya dan penagihan.

Status

Verifikasi berstatus pending sampai berakhir ke status final, dengan reason menjelaskan alasannya:

reason adalah enum terbuka. Pertahankan nilai yang tidak dikenali alih-alih memperlakukan respons sebagai tidak valid.

Bounce, penolakan operator, atau batas waktu pengiriman dapat membuat sesi tetap tertunda karena penerima mungkin masih memiliki kode yang valid. Habisnya rencana pengiriman saja tidak berarti sesi gagal. Lihat Event Verify untuk kondisi kegagalannya.

Lacak verifikasi di dashboard

Halaman Verifications menampilkan semua verifikasi yang dibuat workspace, dapat difilter berdasarkan status. Setiap baris menampilkan penerima, rencana kanal, kanal terakhir, waktu kedaluwarsa dan verifikasi, serta metadata. Kode yang dihasilkan tidak ditampilkan.

Pengaturan verifikasi

Halaman Configure mengatur siklus verifikasi workspace. Setiap field menampilkan nilai efektif: override Anda jika sudah diatur, atau nilai default platform Bird.

• Duration: berapa lama kode tetap valid. Default 10 menit; 1 menit hingga 999 menit.
• Maximum Retries: berapa kali percobaan pengecekan sebelum verifikasi gagal dengan attempts_exhausted. Default 5; 1 hingga 10.
• Retry Delay: jeda sebelum kode baru dapat dikirim ke penerima yang sama. Default 60 detik; 0 hingga 3600.

Panjang kode bukan field di halaman ini: kode default 6 digit, numerik, dan options.code_length mengatur 4 hingga 8 digit per permintaan.

Perlindungan terhadap penyalahgunaan

Terlepas dari pengaturan Anda, Verify menerapkan batas platform untuk mencegah lalu lintas OTP disalahgunakan, baik terhadap saldo Anda (pumping SMS) maupun terhadap kotak masuk korban:

• 5 pengiriman per alamat per jam bergulir, mencakup pembuatan dan pengiriman ulang verifikasi. Jika to berisi kedua alamat, masing-masing memiliki kuotanya sendiri.
• 10 pengecekan per set alamat penerima per menit, sebagai tambahan dari batas percobaan verifikasi.

Rencana kanal, bukan batas per jam, yang membatasi perpindahan kanal. Setiap panggilan maju secara ketat, sehingga satu verifikasi mengirim paling banyak satu kali per kanal tersisa.

Mencapai batas mengembalikan 429; tunggu dan coba lagi setelah periode di header Retry-After. Batas permintaan keseluruhan akun Anda terpisah dan disesuaikan dengan paket; lihat Batas laju permintaan.

Mencoba ulang dengan aman

Ketiga endpoint menerima header Idempotency-Key. Kirim nilai unik per permintaan logis. Setelah timeout atau koneksi terputus, mencoba ulang dengan kunci yang sama memutar ulang respons asli. Pemutaran ulang tidak mengirim kode lain atau menggunakan percobaan pengecekan tambahan, dan menyertakan header Idempotency-Replay. Lihat idempotensi untuk format kunci dan masa retensi.

Biaya dan penagihan

Penagihan berlaku untuk setiap kode yang dikirim. Setiap kode yang dikirim dibebankan ke saldo Anda sesuai tarif kanal untuk tujuan tersebut. Pengiriman ulang atau fallback ke kanal lain menambah satu tagihan per pengiriman. Biaya Bird sendiri diambil saat pengiriman diproses dan tetap berlaku terlepas dari apakah kode sampai; pada SMS dan WhatsApp biaya pihak ketiga menyusul saat pesan terkirim. Rute gratis dan pengecekan tidak dikenakan biaya; pengiriman yang ditolak sebelum penagihan tidak dikenakan biaya. Metode pembayaran dan saldo membahas saldo dan pengisian ulang.

Telegram menagih pada titik berbeda dalam pengiriman. Sebelum pesan keluar, Telegram ditanya apakah nomor tersebut dapat menerimanya; tagihan muncul ketika jawabannya ya, dengan tarif tetap di seluruh dunia, dan nomor yang tidak dapat dijangkau gratis serta lanjut ke kanal berikutnya tanpa tagihan. Jadi tagihan Telegram berarti pesan diterima untuk dikirim, bukan berarti sudah sampai: kode yang kemudian tidak terkirim tetap ditagih, dan verifikasi membayar lagi untuk kanal tujuan fallback. Jika Anda tidak menginginkan tagihan kedua itu, hapus Telegram dari urutan kanal untuk negara tersebut di halaman Countries.

Langkah selanjutnya