FAQ Voice API

Bird Voice memungkinkan Anda melakukan panggilan ke nomor telepon melalui SIP trunk. Sistem telepon Anda terhubung ke Bird, dan Bird merutekan setiap panggilan melalui operator ke jaringan telepon publik (PSTN). Anda menyediakan PBX atau softphone sendiri; Bird menangani sisi operator.

Sekitar sepuluh menit. Buat SIP trunk, verifikasi caller ID, aktifkan negara tujuan, dan arahkan sistem telepon Anda ke alamat trunk. Panduan panggilan pertama memandu Anda melalui seluruh prosesnya.

Tiga hal dari sisi Anda: SIP trunk dengan perangkat Anda yang diizinkan (berdasarkan rentang IP atau API key), caller ID terverifikasi (nomor yang Anda tampilkan sebagai penelepon), dan negara tujuan yang diaktifkan. Bird menambahkan routing ke workspace Anda, yang merupakan prasyarat keempat dan dilakukan di sisi Bird.

Tidak. Sistem telepon apa pun yang mendukung SIP bisa digunakan: softphone seperti Zoiper atau Linphone di laptop, PBX seperti Asterisk atau FreeSWITCH, atau sistem komersial seperti 3CX atau FreePBX. Bird memberikan Anda domain SIP, dan Anda mengarahkan perangkat Anda ke sana.

Ya. Anda dapat melakukan panggilan dari aplikasi Telepon di dasbor menggunakan WebRTC.

Per panggilan, dengan tarif yang tergantung pada negara tujuan. Setiap tarif memiliki increment penagihan: waktu minimum yang ditagih, lalu langkah pembulatan setelahnya. Tarif dengan minimum satu menit dan langkah enam detik menagih panggilan 10 detik sebagai satu menit penuh.

Waktu yang ditagih berjalan dari saat nomor yang dipanggil mengangkat hingga saat panggilan berakhir. Waktu dering tidak ditagih, jadi panggilan yang tidak dijawab tidak dikenakan biaya.

Prabayar, dari dompet organisasi Anda. Bird memeriksa saldo Anda sebelum menghubungi operator, jadi panggilan yang tidak dapat ditanggung dompet Anda akan ditolak di awal dengan insufficient_balance, bukan ditagih setelahnya.

Ya. Batas pengeluaran suara harian berlaku per organisasi, dan direset pada awal setiap hari UTC. Setelah melewati batas, panggilan ditolak dengan daily_spend_exceeded. Jumlahnya tergantung pada paket Anda, dan Bird dapat menaikkannya atas permintaan.

Buka panggilan di log panggilan. Biaya muncul di catatan setelah dihitung, dengan presisi penuh, sebelum pajak. Untuk total dari beberapa panggilan, ekspor daftar panggilan yang difilter sebagai CSV dari halaman Calls, atau periksa tagihan dan penggunaan Anda.

Tiga batas: berapa banyak panggilan yang boleh berlangsung bersamaan (panggilan bersamaan), berapa banyak panggilan baru yang boleh Anda mulai per detik (panggilan per detik), dan berapa banyak yang boleh Anda belanjakan untuk voice dalam satu hari UTC (pengeluaran harian). Masing-masing diatur per organisasi, dan jumlahnya tergantung pada paket Anda.

Panggilan ditolak saat pengaturan, sebelum operator dihubungi. Catatan panggilan menyebutkan batas mana yang tercapai: concurrent_calls_exceeded, calls_per_second_exceeded, atau daily_spend_exceeded. Sistem telepon Anda menerima SIP 503.

Ya. Hubungi dukungan untuk meminta batas panggilan bersamaan atau panggilan per detik yang lebih tinggi. Batas pengeluaran harian tergantung pada paket Anda dan juga bisa dinaikkan.

Periksa alasan yang tercatat di catatan panggilan. Dialer bisa mencapai calls_per_second_exceeded meskipun jauh dari batas panggilan bersamaan, karena kedua batas tersebut independen. Perlambat kecepatan dial dan coba lagi; mencoba ulang segera akan mendapat jawaban yang sama.

SIP trunk adalah koneksi antara sistem telepon Anda dan Bird. SIP (Session Initiation Protocol) adalah bahasa yang digunakan sistem telepon untuk mengatur panggilan, dan trunk adalah jalur yang dilalui panggilan tersebut. Bird memberikan alamat trunk ke workspace Anda, dan Anda mengarahkan sistem telepon Anda ke alamat tersebut.

Sebagian besar workspace hanya membutuhkan satu. Buat lebih banyak jika Anda menginginkan aturan akses terpisah per lokasi atau per sistem, karena daftar IP yang diizinkan, API key yang diizinkan, dan pengaturan Digest semuanya per trunk.

Domain SIP trunk (disalin dari halaman trunk), username bird, dan password (secret dari API key yang diizinkan pada trunk). Kirim panggilan ke domain SIP pada port 5060 (UDP atau TCP) atau 5061 (TLS).

Ya, dengan daftar IP yang diizinkan, API key yang diizinkan, atau keduanya. Tambahkan alamat publik tempat perangkat Anda mengirim SIP, atau wajibkan setiap panggilan untuk mengautentikasi dengan API key melalui SIP Digest. Keduanya berlaku pada panggilan berikutnya.

Domain SIP trunk berhenti menerima panggilan baru secara langsung. Panggilan yang sedang berlangsung tetap dilanjutkan, dan catatan panggilan yang dibuat melalui trunk tetap ada di log panggilan Anda.

PBX Anda mengirim panggilan, Bird menjawab dengan tantangan 407, dan PBX Anda mengirim ulang panggilan dengan header Proxy-Authorization yang dihitung dari username bird dan secret API key Anda sebagai kata sandi. PBX Anda mengirim hash dari kata sandi, bukan kata sandi itu sendiri.

SHA-256 dan MD5. Bird menawarkan SHA-256 terlebih dahulu dan MD5 kedua secara default, dan PBX Anda memilih yang pertama yang didukungnya. Jika perangkat Anda hanya mendukung MD5 dan salah menangani tantangan yang diawali SHA-256, atur trunk ke MD5 saja.

Ya. Ketika trunk memiliki keduanya, alamat sumber diperiksa sebelum Bird meminta kata sandi, sehingga panggilan dari alamat yang tidak terdaftar ditolak terlepas dari kredensial yang dibawanya.

Tambahkan key baru ke trunk terlebih dahulu, pindahkan perangkat Anda, lalu cabut yang lama. Mencabut atau menghapus key akan langsung menghilangkan kemampuan autentikasinya di setiap trunk yang mengizinkannya.

Caller ID adalah nomor telepon yang diizinkan oleh workspace Anda untuk ditampilkan sebagai penelepon pada panggilan keluar. Bird memeriksa nomor penelepon yang dimasukkan perangkat Anda di header SIP From terhadap daftar ini pada setiap panggilan, sehingga panggilan hanya keluar dengan nomor yang sudah Anda verifikasi.

Tambahkan nomor di halaman Numbers dalam format E.164. Bird akan segera melakukan panggilan verifikasi ke nomor tersebut. Jawab panggilan, dengarkan kode enam digit, lalu masukkan di dashboard. Anda mendapat lima kali percobaan, dan nomor tersebut dapat digunakan segera setelah salah satu kode diterima.

Jika percobaan telah habis, gunakan Get a new code pada baris nomor tersebut untuk panggilan verifikasi baru. Jika nomor masih menunggu kodenya, hapus caller ID dan tambahkan nomor tersebut kembali.

Arahkan ke telepon yang bisa Anda angkat selama satu menit saat verifikasi berlangsung, lalu kembalikan. Untuk nomor yang tidak menerima panggilan sama sekali, hubungi dukungan.

Sejak saat itu, setiap panggilan yang menampilkan nomor tersebut ditolak dengan caller_id_not_verified. Panggilan yang sedang berlangsung tetap dilanjutkan, dan catatan panggilan yang menggunakan nomor tersebut tetap seperti adanya.

Penipuan pulsa bekerja dengan menghubungi negara-negara mahal yang tidak pernah Anda maksudkan untuk dihubungi. Negara yang Anda aktifkan adalah negara tempat Anda bisa dikenakan tagihan, jadi menonaktifkan yang lainnya membatasi risiko Anda jika seseorang membobol sistem telepon Anda.

Temukan negara di halaman Destinations menggunakan kotak pencarian (cocok berdasarkan nama atau kode dua huruf) dan aktifkan toggle-nya. Perubahan berlaku mulai saat itu.

Panggilan ke negara berisiko tinggi itu mahal, dan siapa pun yang mengoperasikan nomor yang Anda hubungi mendapat bagian dari biayanya. Ini adalah negara yang ditargetkan penyerang jika mereka membobol sistem telepon. Biarkan nonaktif kecuali Anda memiliki kepentingan bisnis di sana, dan periksa tarifnya sebelum Anda mengaktifkannya.

Hubungi dukungan untuk membukanya bagi akun Anda. Available berarti Anda dapat mengaktifkannya; Not supported berarti Bird saat ini tidak dapat melakukan panggilan ke negara tersebut dari akun Anda.

Negara yang tersedia masih bisa memiliki tujuan spesifik di dalamnya yang belum dijangkau oleh routing. Kirim ID panggilan ke dukungan dan mereka akan memperluas routing untuk mencakupnya.

Dua header: To (nomor yang dipanggil) dan From (nomor yang Anda tampilkan sebagai penelepon, yang harus berupa caller ID terverifikasi). Keduanya harus berupa nomor internasional lengkap dalam format E.164, diawali dengan + diikuti kode negara dan nomor nasional. Tidak diperlukan header kustom.

STIR/SHAKEN adalah tanda tangan yang digunakan operator saat memutuskan apakah akan meneruskan panggilan tanpa label. Panggilan ke Amerika Serikat dan Prancis membawanya secara otomatis tanpa perlu Anda konfigurasi. Panggilan membawa level B secara default; level A (yang terkuat) tersedia berdasarkan permintaan.

Buka panggilan di log panggilan. Sistem telepon Anda menerima SIP 503 biasa, tetapi alasan spesifik tercatat di catatan panggilan yang hanya bisa Anda baca. Panel di atas detail menyebutkan penyebabnya dan menautkan ke pengaturan yang memperbaikinya.

Hanya setelah penyebabnya hilang. Panggilan yang ditolak karena calls_per_second_exceeded akan mendapat jawaban yang sama sampai Anda memperlambat kecepatan dial. Baca alasan penolakan sebelum mencoba ulang.

Lima: Answered (nomor yang dipanggil mengangkat), No answer (berdering hingga habis), Failed (panggilan tidak berhasil, baik Bird menolaknya atau operator gagal memprosesnya), Rejected (operator menolak panggilan secara langsung), dan Unknown (hasilnya tidak dapat ditentukan).

Keduanya muncul sebagai Failed. Alasan penolakan yang membedakannya: hanya penolakan Bird yang memilikinya. Panggilan gagal dengan alasan penolakan menunjuk ke pengaturan di sisi Anda atau Bird; yang tanpa alasan penolakan biasanya menunjuk ke nomor yang Anda hubungi.

Ya. Tab Live di halaman Calls menampilkan daftar panggilan di trunk Anda saat ini, beserta jumlahnya. Panggilan aktif ditampilkan sebagai Ringing (menunggu pihak lain mengangkat) atau In progress (terhubung). Tab ini diperbarui setiap beberapa detik.

Durasi total dihitung dari saat Bird menerima panggilan hingga pemutusan. Waktu yang ditagihkan dihitung dari saat dijawab hingga pemutusan. Selisihnya adalah waktu dering yang tidak diangkat, jadi selisih yang besar perlu diperiksa terkait nomor yang Anda hubungi. Panggilan yang tidak dijawab tidak dikenakan biaya.

Tiga cara: unduh CSV dari halaman Calls (mengekspor setiap catatan yang sesuai dengan filter Anda saat ini, bukan hanya halaman yang terlihat), baca melalui API dengan API key yang memiliki cakupan voice:read, atau gunakan Bird CLI dengan bird voice list.

Tiga: voice_call.initiated (Bird menerima panggilan dan mulai melakukan routing), voice_call.answered (nomor yang dipanggil mengangkat), dan voice_call.ended (panggilan selesai, beserta hasilnya). Panggilan yang tidak dijawab tidak pernah mengirimkan event answered.

Panggilan yang ditolak Bird setelah menerima INVITE tetap diakhiri dengan voice_call.ended, membawa status failed dan sip_response_code 503. Jadi setiap panggilan yang Anda ketahui dibuka juga akan ditutup. Panggilan yang sama sekali tidak dapat diterima Bird (ditolak di lapisan SIP) tidak pernah menghasilkan event apa pun.

Ya. Pengiriman tidak berurutan, jadi answered bisa sampai ke Anda setelah ended. Urutkan berdasarkan field timestamp, dan biarkan event yang tiba lebih lambat dengan timestamp lebih awal kalah.

Deduplikasi berdasarkan header HTTP webhook-id. Bird mengirim setidaknya sekali, dan event initiated suatu panggilan bisa dipublikasikan lebih dari sekali ketika retry sinyal diputar ulang. Panggilan yang sama, tahap yang sama, webhook-id yang sama.

Keduanya ada di catatan panggilan, bukan di event. Status failed pada voice_call.ended tidak memberi tahu Anda apakah Bird atau operator yang menyebabkannya. Buka panggilan di log panggilan untuk melihat alasan penolakan, dan biaya akan muncul di sana setelah panggilan dinilai.

Panggilan yang tidak dapat diterima Bird ditolak di lapisan SIP, sebelum catatan dibuat. Periksa empat hal: trunk memiliki rentang IP atau API key yang mengizinkan perangkat Anda, panggilan datang dari alamat yang ada di daftar IP yang diizinkan trunk (di belakang NAT, itu adalah alamat publik router), kredensial Digest benar (username bird, secret API key yang tepat, algoritma yang ditawarkan trunk), dan domain SIP cocok persis dengan domain trunk.

Buka panggilan di log panggilan. Panel di atas detail menyebutkan penyebab dan menautkan ke pengaturan yang memperbaikinya. Tujuh alasan yang bisa Anda perbaiki adalah source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded, dan calls_per_second_exceeded.

Beberapa perangkat salah menangani tantangan yang dimulai dengan SHA-256. Atur algoritma Digest trunk ke MD5 saja, dan PBX Anda akan mendapatkan tantangan yang dipahaminya.

Klien Anda berada di belakang NAT (router atau firewall yang menulis ulang alamat) dan media dikirim ke alamat privat yang tidak dapat dijangkau sisi lain. Aktifkan penanganan NAT atau STUN pada klien Anda agar mengiklankan alamat publiknya dalam penawaran media.

Bisa. Bird mendukung TLS pada port 5061 untuk sinyal SIP, sehingga pengaturan panggilan dienkripsi saat transit. UDP dan TCP pada port 5060 tidak dienkripsi. Pilih transport sesuai kebutuhan keamanan Anda.

Setiap event ditandatangani dengan HMAC. Verifikasi tanda tangan dengan secret endpoint Anda sebelum memproses payload, dan rotasi secret tersebut dari dashboard kapan pun diperlukan.

Di region tempat organisasi Anda di-host, baik us1 atau eu1. API key Anda membawanya dalam prefiks (bk_us1_, bk_eu1_), yang memungkinkan SDK dan CLI memilih endpoint yang tepat tanpa Anda perlu mengonfigurasinya.

Hanya sesuai scope yang Anda tetapkan. Sebuah key membawa daftar scope, masing-masing pada level read atau write. Key dengan voice:write dapat mengautentikasi panggilan pada trunk; key dengan voice:read dapat melihat daftar catatan panggilan. Key tidak dapat mengakses channel atau pengaturan di luar scope-nya.

Alasan spesifik dicatat pada catatan panggilan yang hanya bisa Anda baca. Mengembalikan 503 generik ke lapisan SIP mencegah pihak yang memindai trunk Anda mengetahui trunk, nomor, dan tujuan mana yang ada.

Sertifikasi dan dokumentasi keamanan tersedia di Trust Center di trust.bird.com. Perjanjian pemrosesan data, pernyataan privasi, dan kebijakan penggunaan yang dapat diterima dipublikasikan di bird.com/legal. Untuk kuesioner vendor, tim akun Bird Anda yang menanganinya.