Menerima panggilan

Nomor yang dimiliki workspace Anda dapat mengirim panggilan masuk ke trunk SIP, mengalihkannya ke nomor terverifikasi, menjalankan sequence yang sudah dipublikasikan, 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 publikasi dan penguji draf masuk.
• 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 memanggil sistem telepon Anda sendiri di alamat yang Anda deklarasikan pada trunk. Aktifkan arahnya terlebih dahulu, karena nomor hanya dapat diarahkan ke trunk yang sudah menerima panggilan masuk.

1. Buka Voice > Trunk SIP, buka trunk tersebut, dan di bagian Panggilan masuk pilih Aktifkan panggilan masuk.
2. Tambahkan minimal satu gateway di bagian yang sama. Trunk tanpa gateway menolak setiap panggilan masuk ke nomor-nomor yang dijawabnya.
3. Buka Voice > Nomor, buka nomor tersebut, dan di bagian Perutean masuk pilih Kirim ke trunk SIP.
4. Pilih trunk lalu klik Simpan. Hanya trunk dengan panggilan masuk aktif yang muncul di daftar.

Kolom Digunakan untuk pada daftar Nomor kemudian menampilkan nomor tersebut sebagai dikirim ke trunk itu, dan halaman trunk sendiri mencantumkan nomor-nomor yang dijawabnya.

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);
}

for number, err := range client.Voice.Numbers.List(context.Background(), bird.VoiceNumbersListParams{
	Search: "31201234567",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number.Id, number.PhoneNumber)
}

foreach ($bird->voice->numbers->list(['search' => '31201234567']) as $number) {
    echo $number->getId(), ' ', $number->getPhoneNumber(), "\n";
}

bird voice numbers list --search 31201234567

curl -X GET "https://{region}.platform.bird.com/v1/voice/numbers" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "search=31201234567"

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);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteTrunk(bird.VoiceCallRouteTrunk{
	TrunkId: "spt_01krdgeqcxet5s7t44vh8rt9mg",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'trunk',
            'trunk_id' => 'spt_01krdgeqcxet5s7t44vh8rt9mg',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --body-file - <<'JSON'
{
  "inbound_configuration": {
    "route": {
      "type": "trunk",
      "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
    }
  }
}
JSON

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

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:

Gateway dengan prioritas yang sama menerima bagian panggilan yang setara, dan salah satu dari mereka bisa dicoba lebih dulu pada panggilan tertentu. Untuk mengalihkan pengiriman ke alamat kedua, berikan gateway tersebut angka prioritas yang lebih besar: gateway itu dicoba ketika yang pertama tidak menjawab.

Kedua format nomor adalah template dengan satu placeholder, {number}, yang mewakili nomor tanpa awalan +. Format destination 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);

gateway = client.voice.trunks.gateways.create(
    "TRUNK_ID",
    sip_uri="sip:pbx.example.com:5060",
    priority=0,
    destination_format="1234#{number}",
)
print(gateway.id, gateway.priority)

gateway, err := client.Voice.Trunks.Gateways.Create(context.Background(), "TRUNK_ID", bird.VoiceTrunksGatewaysCreateParams{
	SipURI:            "sip:pbx.example.com:5060",
	Priority:          0,
	DestinationFormat: bird.Ptr("1234#{number}"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(gateway.Id, gateway.Priority)

$gateway = $bird->voice->trunks->gateways->create(
    'TRUNK_ID',
    (new VoiceTrunkGatewayCreate())
        ->setSipUri('sip:pbx.example.com:5060')
        ->setPriority(0)
        ->setDestinationFormat('1234#{number}'),
);
echo $gateway->getId(), ' ', $gateway->getPriority(), "\n";

bird voice trunks gateways create <trunk-id> \
  --destination-format '1234#{number}' \
  --priority 0 \
  --sip-uri sip:pbx.example.com:5060

curl -X POST "https://{region}.platform.bird.com/v1/voice/trunks/{trunk_id}/gateways" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sip_uri": "sip:pbx.example.com:5060",
    "priority": 0,
    "destination_format": "1234#{number}"
  }'

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:

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);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteForward(bird.VoiceCallRouteForward{
	ForwardTo: "+14155551234",
	ForwardAs: "dialed_number",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'forward',
            'forward_to' => '+14155551234',
            'forward_as' => 'dialed_number',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --route forward --forward-to +14155551234 --forward-as dialed_number

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "forward",
        "forward_to": "+14155551234",
        "forward_as": "dialed_number"
      }
    }
  }'

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:

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 pemanggil itu sendiri, sehingga telepon berdering seolah-olah mereka menelepon langsung dan panggilan dapat dikembalikan dari log panggilan. 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 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 rute sequence, periksa juga halaman Eksekusi sequence untuk mengetahui titik masuk dan versi yang dijalankan. 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:

• 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:

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