Menerima Kode SMS dan Panggilan Suara lewat Webhook: Panduan API

Webhook mengirim setiap SMS dan panggilan di nomor Anda ke server Anda. Panggilan singkat datang bersama teksnya dan kode yang dibacakan di dalamnya.

Webhook mengirim setiap SMS dan panggilan di nomor Anda ke server Anda saat itu masuk. Sejak November 2026, panggilan singkat datang bersama teksnya dan kode yang dibacakan di dalamnya, sehingga kode suara sampai ke kode program Anda sebagai teks.

Panduan ini menyiapkan penerima webhook, memeriksa bahwa setiap permintaan benar-benar berasal dari kami, dan menangani kedua jenis kode. Panduan ini mengasumsikan Anda sudah punya kunci API dan sebuah nomor. Jika belum, mulailah dengan mengotomatiskan verifikasi SMS dengan API.

Mengapa sebagian kode datang sebagai panggilan

Banyak layanan menawarkan pilihan “telepon saya saja” ketika SMS tidak datang, dan sebagian hanya mengirim kode lewat suara. Sebuah robot membacakan angkanya. Dengan nomor pribadi dari SMS Activate App, panggilan itu masuk ke nomor Anda seperti halnya SMS.

Setiap panggilan terekam yang berdurasi hingga satu menit diubah menjadi teks saat panggilan masuk. Anda mendapatkan:

  • transcript: isi panggilan, atau null.
  • code: kode verifikasi yang dibacakan di dalamnya (4 sampai 8 digit), atau null.
  • transcriptStatus: done, empty (tidak ada ucapan), failed, toolong (lebih dari satu menit), overbudget atau off.

Tautan rekaman berlaku selama 24 jam. Teksnya tetap tersimpan.

Langkah 1: arahkan nomor ke server Anda

Atur webhook untuk satu nomor:

Alamat harus menggunakan HTTPS dan menjawab pemeriksaan kami dengan status 2xx sebelum disimpan. Untuk menerima event dari semua nomor Anda sekaligus, atur webhookUrl pada akun dengan PATCH /v1/me sebagai gantinya.

Langkah 2: ambil secret penandatanganan

Jawabannya {"secret": "whsec_..."} dan hanya ditampilkan sekali. Simpan secret ini bersama kunci API Anda. Setiap panggilan ke endpoint ini menerbitkan secret baru, dan secret lama berhenti berlaku pada pengiriman berikutnya. Karena itu, ganti secret hanya ketika Anda bisa memperbarui server pada saat yang sama.

Langkah 3: verifikasi setiap permintaan

Setiap permintaan membawa tiga header:

  • x-vpn-event: sms.received, call.received, recording.ready, dan lainnya.
  • x-vpn-timestamp: waktu penandatanganan, dalam detik Unix.
  • x-vpn-signature: v1= diikuti HMAC-SHA256 dalam format heksadesimal.

Tanda tangan adalah HMAC-SHA256 dengan secret Anda atas v1.<timestamp>.<raw body>. Hitung atas byte mentah, sebelum parsing JSON apa pun, dan tolak timestamp yang selisihnya lebih dari lima menit dari jam server Anda.

Di Node.js dengan Express:

Jawab dengan cepat memakai status 2xx, lalu kerjakan tugas yang lambat sesudahnya.

Langkah 4: ambil kode dari kedua jenis event

Sebuah SMS (sms.received):

Rekaman sebuah panggilan (recording.ready, beberapa detik setelah panggilan berakhir):

Satu handler menangani keduanya:

Gunakan field code daripada mengurai transkrip sendiri: robot sering mengulang angka atau membacanya satu per satu, dan code sudah menyimpannya sebagai satu string.

Langkah 5: uji sebelum lalu lintas sungguhan

  • POST /v1/me/webhook-test mengirim event webhook.test ke penerima Anda.
  • GET /v1/me/webhook-deliveries menampilkan daftar pengiriman terakhir: event-nya, apakah terkirim, kode status dari server Anda, dan jumlah percobaan.

Jika pengiriman gagal, periksa di sana lebih dulu. Penyebab yang umum adalah secret yang salah, body yang di-parse sebelum verifikasi, atau jawaban yang lambat.

Tanpa webhook? Baca panggilan lewat API

Tanpa server, Anda bisa membaca panggilan sebuah nomor saat diperlukan:

Setiap panggilan membawa transcript, code dan transcriptStatus yang sama. Di akun Anda pada situs web, kode tampil di bawah panggilan dan bisa disalin dengan satu ketukan.

Biaya panggilan dan SMS

Panggilan masuk (per menit) dan SMS pada sebuah nomor dibebankan ke saldo Anda dengan harga per negara, yang dikembalikan sebagai usagePricing (callCents, smsCents, advanceUsd) pada daftar negara, hasil pencarian, dan nomor Anda. Jika saldo kosong, nomor tetap berfungsi sampai batas uang muka kecil. Setelah batas itu terlewati, panggilan masuk ditolak sampai Anda mengisi saldo, sedangkan SMS tetap diterima. Lihat harga.

Langkah berikutnya