Sign inGet Started

Menerima panggilan

Nomor yang dimiliki workspace Anda dapat mengirim panggilan masuk ke trunk SIP, meneruskannya ke nomor terverifikasi, menjalankan sequence yang sudah dipublikasikan, membunyikan ring group berisi orang-orang yang sedang online di browser phone, atau menolaknya. Setiap nomor memiliki satu rute pada satu waktu: rutenya sendiri, atau rute default workspace jika nomor tersebut tidak memilikinya.

Rute default workspace dimulai sebagai reject, sehingga nomor yang belum dikonfigurasi siapa pun akan menolak penelepon alih-alih tidak memiliki jawaban sama sekali. Ubah default untuk memberikan jawaban yang sama ke setiap nomor semacam itu. Lihat Atur rute default.

Untuk menangani panggilan masuk dalam alur bawaan Bird, publikasikan sequence dan hubungkan nomor ke titik masuk panggilannya. Titik masuk yang dipilih harus menerima data kosong.

Prasyarat

Sebelum Anda mengarahkan nomor ke sebuah jawaban:

  • Nomor yang dapat menerima panggilan. Buka Voice > Numbers dan periksa kolom Directions untuk tanda inbound. Nomor yang Anda daftarkan sebagai caller ID dari operator lain tidak menerima panggilan di sini: operator tersebut yang merutekan panggilan ke nomor itu, jadi nomor tersebut tidak memiliki jawaban.
  • Untuk pengiriman ke trunk: sebuah trunk SIP dengan panggilan masuk aktif dan minimal satu gateway pengiriman.
  • Untuk penerusan: sebuah caller ID terverifikasi sebagai tujuan penerusan.
  • Untuk sequence: sequence aktif yang sudah dipublikasikan di workspace yang sama, dengan titik masuk panggilan yang menerima data titik masuk kosong. Di bagian Inbound routing, pilih Run a sequence, pilih sequence dan titik masuk panggilan, lalu simpan. Panduan pembuat sequence menjelaskan pengujian dan publikasi.
  • Untuk ring group: sebuah ring group yang anggotanya online di browser phone. Di bagian Inbound routing, pilih Ring a ring group, pilih grupnya, lalu simpan.
  • Untuk mengubah pengaturan melalui API atau CLI: sebuah kunci API yang memiliki scope voice_management pada level write. Scope tersebut mencakup konfigurasi voice; scope voice mencakup lalu lintas panggilan dan statistik, jadi membaca log panggilan memerlukan scope yang satunya.

Kirim panggilan ke trunk SIP

Pengiriman menghubungi sistem telepon Anda sendiri di alamat yang Anda deklarasikan pada trunk. Aktifkan arah ini terlebih dahulu, karena nomor hanya dapat diarahkan ke trunk yang sudah menerima panggilan masuk. Siapkan trunk SIP membahas seluruh penyiapan secara berurutan.

  1. Buka Voice > SIP Trunks, buka trunk tersebut, dan di bagian Inbound calling pilih Enable inbound.
  2. Di bagian Inbound routing, tambahkan gateway Anda di tab Gateways, masukkan ke dalam grup di tab Groups, dan atur Default route di tab Rules ke Route to group. Pilih Review and save, lalu konfirmasi.
  3. Buka Voice > Numbers, buka nomor tersebut, dan di bagian Inbound routing pilih Deliver to a SIP trunk.
  4. Pilih trunk lalu pilih Save. Hanya trunk dengan panggilan masuk aktif yang muncul di daftar.

Kolom Used for pada daftar Numbers kemudian menampilkan nomor tersebut sebagai dikirim ke trunk itu, dan halaman trunk tersebut mencantumkan nomor-nomor yang dijawabnya.

Trunk dengan panggilan masuk aktif memiliki Inbound routing sendiri: Gateways yang dapat dijangkaunya, Groups yang mencoba gateway tersebut satu per satu, Rules opsional, dan Default route. Bird mengirim panggilan ke grup, sehingga gateway hanya berdering jika aturan atau rute default mengirim panggilan ke grup yang memuatnya. Failover dan bagi panggilan masuk menunjukkan cara menyiapkan failover dan pembagian beban. Rutekan panggilan trunk masuk berdasarkan asal pemanggil dan nomor memberikan contoh aturan yang berfungsi untuk pemanggil seluler dan telepon rumah serta untuk prefiks berdasarkan asal pemanggil.

BagianFungsinya
GatewaysAlamat tujuan pengiriman panggilan, beserta format nomornya
GroupsSekumpulan gateway yang dicoba untuk satu panggilan. Order dapat berupa Sequential (urutan daftar), Random (diacak per panggilan), atau Weighted (Priority terkecil lebih dulu, Weight membagi panggilan dalam satu prioritas). Setiap anggota memiliki Ring time
RulesKondisi opsional, diperiksa secara berurutan. Aturan pertama yang cocok menentukan nasib panggilan
Default routeApa yang terjadi pada panggilan yang tidak cocok dengan aturan mana pun: Route to group, Reject, atau Forward to number

Trunk yang perutean-nya belum pernah disimpan mengirim setiap panggilan ke semua gateway-nya, sesuai urutan prioritas. Setelah Anda menyimpan perutean di dashboard, grup dan rute default yang tersimpan yang menentukan. Rute default tersimpan yang disetel ke Reject menolak setiap panggilan yang tidak cocok dengan aturan mana pun.

Saat Anda menyimpan, dashboard menampilkan peringatan Calls never reach some gateways jika sebuah gateway tidak berada di grup mana pun yang digunakan oleh aturan atau rute default. Panggilan tidak pernah membunyikan gateway semacam itu. Jika rute default menolak dan tidak ada aturan yang mengirim panggilan ke grup, panggilan ditolak sebelum mencapai perangkat Anda, seperti yang dijelaskan di Diagnosis panggilan masuk yang ditolak.

Melalui API, perbarui trunk dengan inbound_enabled: true, tambahkan gateway, lalu arahkan voice record nomor ke trunk tersebut. Voice record memiliki ID yang diawali vnu_, yang berbeda dari ID nda_ yang dikembalikan /v1/numbers untuk nomor yang sama. Mengirimkan ID nda_ ke operasi voice number ditolak dengan 422. Untuk menemukan voice record, cari voice number Anda berdasarkan digit nomor tersebut:

for await (const number of bird.voice.numbers.list({ search: "31201234567" })) {
  console.log(number.id, number.phone_number);
}

Setiap hasil membawa id, phone_number, dan inbound_configuration.route saat ini. Kirim rute trunk ke perbarui voice number dengan id tersebut:

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "trunk", trunk_id: "spt_01krdgeqcxet5s7t44vh8rt9mg" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

Trunk yang panggilan masuknya nonaktif ditolak dengan 412 dan E21052. Rute menggantikan apa pun yang sebelumnya dimiliki nomor tersebut. Mengirim {"type": "reject"} sebagai rute menolak penelepon apa pun default-nya, dan mengirim null mengembalikan nomor ke rute default workspace.

Apa yang dibutuhkan gateway

Gateway adalah satu alamat tujuan pengiriman panggilan, beserta cara peer tersebut menginginkan dua nomor panggilan dituliskan:

PengaturanPenjelasan
SIP URINama host atau alamat IPv4 sistem telepon Anda, dengan port opsional, seperti sip:pbx.example.com:5060. Untuk TLS, gunakan sips:pbx.example.com:5061 atau sip:pbx.example.com:5061;transport=tls. Berikan host saja: URI yang mengandung user part akan ditolak
PriorityUrutan gateway dicoba, dari yang terkecil lebih dulu
Destination formatCara nomor tujuan dituliskan ke peer ini. Default-nya E.164
Origination formatCara nomor pemanggil dituliskan ke peer ini, pada header P-Asserted-Identity panggilan yang dikirim. Default-nya E.164

Di dashboard, URI SIP diisi sebagai Host, Port, dan Transport, dan format tujuan diberi label R-URI user part. Melalui API, keduanya adalah sip_uri dan destination_format. Di dashboard, Anda memilih format dari daftar field, misalnya Without the plus, dan API mengembalikan pilihan yang sama dalam bentuk {number}.

Gateway dengan prioritas yang sama menerima bagian panggilan yang setara, dan salah satu dari gateway itu bisa dicoba lebih dulu pada panggilan tertentu. Untuk mengalihkan pengiriman ke alamat kedua saat gagal, berikan gateway tersebut angka prioritas yang lebih besar: gateway itu dicoba ketika yang pertama tidak menjawab. Prioritas berlaku selama perutean trunk belum pernah disimpan. Setelah perutean disimpan di dashboard, grupnya yang menentukan urutan, dan gateway yang ditambahkan kemudian, termasuk melalui API, baru berdering setelah dimasukkan ke dalam grup.

Kedua format nomor adalah template dengan satu placeholder, {number}, yang mewakili nomor tanpa awalan +. Format tujuan ditempatkan sebelum host URI SIP, jadi 1234#{number} mengirim panggilan ke +31201234567 sebagai sip:1234#31201234567@pbx.example.com:5060. Default untuk keduanya adalah +{number}, yaitu E.164. Format yang tidak mengandung {number} sama sekali mengirim setiap nomor yang dijawab trunk ke satu alamat tetap. Peer yang mengharapkan nomor tanpa + menggunakan {number} saja sebagai formatnya.

Melalui API, tambahkan gateway ke trunk dengan pengaturan ini. Aktifkan panggilan masuk trunk terlebih dahulu: membuat gateway pada trunk tanpa panggilan masuk aktif ditolak dengan 412 dan E21052.

const gateway = await bird.voice.trunks.gateways.create("TRUNK_ID", {
  sip_uri: "sip:pbx.example.com:5060",
  priority: 0,
  destination_format: "1234#{number}",
});
console.log(gateway.id, gateway.priority);

Perbarui gateway untuk mengubah prioritas atau formatnya nanti.

Peringatan: menonaktifkan panggilan masuk pada trunk, atau menghapus trunk tersebut, mengembalikan setiap nomor yang mengarah ke trunk itu ke rute default workspace. Rute default workspace yang menamai trunk tersebut kembali ke reject. Mengaktifkan kembali panggilan masuk tidak memulihkan keduanya, jadi masing-masing harus diarahkan ke trunk lagi.

Atur rute default

Rute default workspace menjawab panggilan untuk setiap nomor yang tidak memiliki rute sendiri. Rute ini dimulai sebagai reject. Nomor yang sudah memiliki rute sendiri tetap mempertahankannya saat default berubah.

  1. Buka Voice > Numbers.
  2. Di samping Calls to numbers without their own route, pilih Change, tentukan jawabannya, lalu simpan.

Perubahan berlaku mulai panggilan berikutnya yang diterima setiap nomor tersebut. Melalui API, perbarui pengaturan voice:

Contoh kode
curl -X PATCH "https://{region}.platform.bird.com/v1/voice/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "trunk",
        "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

Rute default diperiksa dengan cara yang sama seperti rute nomor. Untuk mengembalikan nomor ke default, atur rutenya ke null, atau pilih Use the workspace default pada nomor tersebut.

Teruskan panggilan ke nomor lain

Penerusan menjawab panggilan masuk dan melakukan panggilan kedua ke nomor yang sudah Anda verifikasi, lalu menghubungkan keduanya.

  1. Buka Voice > Numbers, buka nomor tersebut, dan di bagian Inbound routing pilih Forward to another number.
  2. Pilih nomor tujuan penerusan. Daftar berisi caller ID terverifikasi Anda, karena penerusan hanya boleh menargetkan nomor yang sudah Anda buktikan Anda kendalikan.
  3. Pilih nomor mana yang ditampilkan sebagai pemanggil pada panggilan yang diteruskan, lalu klik Simpan.

Melalui API, cari nomor voice Anda berdasarkan digit nomor tersebut untuk membaca ID vnu_-nya, lalu kirim rute forward dengan forward_to dan forward_as:

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "forward", forward_to: "+14155551234", forward_as: "dialed_number" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

forward_to harus berupa caller ID yang verifikasinya sudah selesai. Nomor yang belum Anda daftarkan, atau yang verifikasinya pending atau failed, ditolak dengan 412 dan E21053. Caller ID membahas cara mendaftarkan dan memverifikasi nomor melalui API.

Target penerusan diperiksa saat Anda mengaturnya dan kembali pada setiap panggilan yang diteruskan. Caller ID yang kemudian Anda hapus menghentikan penerusan alih-alih melanjutkannya, dan panggilan masuk ditolak sejak saat itu.

Panggilan yang diteruskan berdering selama 45 detik sebelum dianggap gagal, lebih lama dari pengiriman ke trunk karena ujung seberang biasanya adalah telepon seseorang, bukan sistem telepon.

Penerusan melakukan panggilan, jadi aturan outbound berlaku pada leg kedua: meneruskan ke negara yang belum Anda aktifkan di Tujuan ditolak dengan destination_not_enabled.

Satu penerusan, dua catatan panggilan

Panggilan yang diteruskan menghasilkan dua catatan leg yang berbagi satu call_id:

CatatanPenjelasan
Panggilan masukdirection adalah inbound, dan route menyatakan nomor diatur untuk meneruskan, ke nomor mana, dan nomor mana yang ditampilkan leg penerusan
Panggilan terusandirection adalah outbound, dari nomor yang ditampilkan leg tersebut ke nomor tujuan penerusan Anda. Catatan ini tidak memiliki route sendiri

Gunakan filter call_id pada daftar leg untuk menemukan koneksi terkait, atau buka Voice > Panggilan. Catatan panggilan masuk adalah catatan yang menyatakan apa yang dikonfigurasi pada nomor tersebut.

Pilih nomor mana yang ditampilkan sebagai pemanggil pada panggilan yang diteruskan

Panggilan yang diteruskan memiliki dua nomor yang bisa ditampilkan kepada penjawab, dan pilihan ini memengaruhi apa yang mereka lihat serta seberapa besar kemungkinan operator mencampuri panggilan tersebut:

  • Nomor pemanggil adalah nomor milik pemanggil itu sendiri, sehingga telepon berdering seolah-olah mereka menelepon langsung dan panggilan dapat dibalas dari log panggilan. Nomor pemanggil yang disembunyikan tetap tersembunyi, dan penerima panggilan melihatnya sebagai anonim. Karena nomor tersebut bukan milik Anda, beberapa operator, paling sering di AS dan sebagian Eropa, menandai panggilan semacam itu sebagai tidak terverifikasi, mengganti nomornya, atau menyaringnya.
  • Nomor yang dipanggil adalah nomor yang dihubungi pemanggil, yaitu salah satu nomor Anda. Penjawab melihat nomor Anda yang mana yang dihubungi, bukan siapa yang menelepon.

Tentukan pilihan ini pada setiap penerusan yang Anda tulis melalui API atau CLI. Konfigurasi lama tanpa pilihan tersimpan akan mengembalikan nomor yang dipanggil saat dibaca.

inbound_configuration.forward_as_options pada nomor mencantumkan pilihan yang tersedia bagi editor. Opsi saat ini meliputi nomor pemanggil dan nomor yang dipanggil. Baca opsi tersebut saat membangun integrasi, dan gunakan forward_as yang dikembalikan untuk mengonfirmasi pengaturan yang berlaku.

Pada pembacaan, forward_as adalah nilai yang benar-benar dibawa panggilan, yang bisa berbeda dari nilai terakhir yang ditulis.

Lihat apa yang dilakukan nomor terhadap panggilan

Catatan panggilan masuk memiliki route di samping statusnya, dan route adalah apa yang diatur pada nomor saat panggilan ditangani. Mengubah pengaturan nomor setelahnya tidak mengubah catatan panggilan yang sudah lalu.

route.typeApa yang dilakukan nomor
trunkPanggilan dikirim ke trunk SIP yang disebutkan di trunk_id
forwardPanggilan diteruskan ke nomor di forward_to, menampilkan nomor di forward_as
rejectNomor menolak panggilan tersebut
sequencePanggilan memilih sequence di sequence_id dan entry di entry_node_id
ring_groupPanggilan membunyikan ring group di ring_group_id, yang mungkin sudah dihapus sejak saat itu

route menyatakan apa yang diatur pada nomor, bukan bahwa itu berhasil. Rute trunk pada panggilan yang tidak pernah tersambung berarti nomor diarahkan ke trunk yang tidak menerima panggilan tersebut, dan status panggilan itulah yang membawa hasilnya. route tidak ada pada panggilan keluar dan pada panggilan yang dicatat sebelum field ini ada.

Di dashboard, buka panggilan dari Voice > Leg dan lihat baris Rute masuk, yang menautkan ke nomor yang pengaturannya menentukan panggilan tersebut. Melalui API, route tersedia di GET /v1/voice/legs/{leg_id} dan GET /v1/voice/legs, dan direction memfilter daftar ke panggilan masuk.

Untuk panggilan sequence yang diterima, periksa halaman Runs sequence tersebut untuk mengetahui titik masuk dan versi yang dijalankan. Panggilan yang ditolak karena sequence-nya dijeda, diarsipkan, atau batal dipublikasikan memiliki rute terpilih tetapi tidak memiliki run. Konfigurasi nomor saat ini dapat berbeda dari versi yang disimpan untuk panggilan sebelumnya.

Diagnosis panggilan masuk yang ditolak

Panggilan masuk yang ditolak dicatat dengan status rejected. Dua hal berbeda menghasilkannya, dan rejection_reason adalah yang membedakan keduanya. Untuk membaca alasan penolakan dan rute sequence, Anda memerlukan voice_management:read; tanpa izin tersebut, alasan yang tidak ada bisa berarti detailnya disembunyikan. Minta admin workspace yang memiliki izin tersebut untuk memeriksa ID leg.

  • Ditolak tanpa rejection_reason. Nomor itu sendiri yang menolak panggilan. Panggilan tidak gagal pada pemeriksaan kami mana pun, sehingga tidak menyebutkan alasan, dan route menyatakan apa yang diatur pada nomor. Rute reject berarti nomor yang sengaja diatur untuk menolak, atau nomor tanpa rute sendiri sementara rute default workspace adalah reject.
  • Ditolak dengan rejection_reason. Panggilan gagal pada salah satu pemeriksaan kami sebelum mencapai sistem telepon Anda. Alasan menyebutkan pemeriksaan tersebut. Panggilan yang ditolak mencantumkan setiap alasan beserta perbaikannya.

failed adalah status yang berbeda dan tidak berarti ditolak: artinya panggilan dicoba dan tidak berhasil, dengan sip_response_code membawa respons yang kembali.

Baca route dan rejection_reason bersama-sama untuk membedakan penolakan:

route dan alasanPenyebab
reject, tanpa alasanNomor tersebut memiliki rute sendiri yang disetel ke reject, atau tidak memiliki rute sendiri sementara rute default workspace adalah reject. Buka nomor tersebut untuk melihat yang mana. Menghapus trunk, atau menonaktifkan panggilan masuknya, dapat membuat nomor yang sebelumnya berfungsi berakhir di sini
trunk, tanpa alasanPerutean trunk itu sendiri yang menolak panggilan: Default route-nya (atau aturan yang cocok) diatur ke Reject. Inilah yang terjadi pada trunk yang disimpan dengan gateway tetapi tanpa grup, atau dengan rute default yang masih reject. Buka Inbound routing trunk tersebut, masukkan gateway ke dalam grup, lalu atur Default route ke grup itu
forward, tanpa alasanTarget penerusan bukan lagi caller ID terverifikasi. Verifikasi ulang di Caller ID, atau teruskan ke nomor lain
forward, destination_not_enabledLeg kedua tidak dapat dilakukan ke negara target penerusan. Aktifkan negara tersebut di Tujuan

Nomor yang diarahkan ke trunk tanpa gateway tersimpan menolak panggilan sebelum catatan dibuat, sehingga panggilan tidak muncul di log leg. Tambahkan gateway di Inbound routing trunk tersebut, lalu simpan peruteannya.

Batas akun berlaku juga untuk panggilan masuk: melewati saldo wallet Anda, batas pengeluaran voice harian organisasi Anda, atau batas konkurensi dan per-detik Anda, panggilan masuk ditolak dengan alasan yang sesuai. Ringkasan Voice membahas batas-batas tersebut.

Periksa biaya panggilan yang diterima

Menerima panggilan dikenakan biaya. Tarifnya bergantung pada negara dan jenis nomor yang menerima, dan dipublikasikan per negara di bawah Menerima panggilan pada halaman harga voice, bersama tarif untuk panggilan yang Anda lakukan.

Penerusan ditagih sebagai dua panggilan: panggilan masuk dengan tarif penerimaan, dan leg yang kami lakukan dengan tarif outbound untuk nomor tujuan penerusan Anda. Satu biaya penanganan dikenakan sekali untuk panggilan tersebut, bukan sekali per leg.

Wallet diperiksa sebelum panggilan masuk dikirim, sehingga saldo yang tidak mencukupi berarti panggilan ditolak, bukan ditagihkan kepada Anda setelahnya. Biaya dan penagihan membahas cara waktu yang dapat ditagih, tarif, dan wallet bekerja untuk kedua arah.

Langkah selanjutnya

HalamanYang dibahas
Trunk SIPMembuat trunk, dua arahnya, dan mengontrol siapa yang boleh mengirim
Caller IDMendaftarkan nomor dan membuktikan bahwa Anda mengendalikannya
Ring groupMembunyikan telepon tim Anda di browser phone saat panggilan masuk
Log panggilanSetiap field pada catatan panggilan, dan setiap alasan penolakan
Peristiwa VoiceMendapatkan hasil panggilan yang dikirim ke sistem Anda sendiri
Pemecahan masalah VoiceMendiagnosis panggilan yang tidak berhasil, berdasarkan gejalanya

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.