Mengelola nomor telepon Anda

Setelah nomor dialokasikan ke workspace Anda, API numbers memungkinkan Anda melihat daftar nomor yang Anda miliki, menemukan satu nomor berdasarkan pengenalnya, memberi label dengan nama dan referensi Anda sendiri, serta membatalkan atau melepaskannya saat tidak diperlukan lagi. Membaca memerlukan kunci API dengan cakupan numbers di level read; mengubah, membatalkan, atau melepaskan nomor memerlukan level write.

Halaman Numbers di dashboard menampilkan nomor yang sama.

Daftar semua nomor yang Anda miliki

GET /v1/numbers mengembalikan nomor yang saat ini dialokasikan ke workspace Anda, terbaru lebih dulu, baik dedicated maupun shared. Setiap halaman memuat 25 nomor kecuali Anda meminta hingga 100 dengan limit.

Daftar ini dipaginasi dengan cursor. Kirimkan next_cursor dari suatu halaman kembali sebagai starting_after untuk membaca halaman berikutnya, dan berhenti saat next_cursor bernilai null. SDK mengikuti cursor untuk Anda. Contoh di bawah mempersempit daftar ke country_code: "GB"; hilangkan filter untuk menelusuri semua nomor yang Anda miliki:

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

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

Daftar ini tidak memuat total. Untuk menghitung nomor Anda, telusuri semua halaman hingga akhir dan hitung entri-entrinya. Mengirimkan include_total ditolak dengan 422 dan E01029.

Setiap entri memuat status dan ownership. Jika suatu negara tidak mewajibkan dokumen kepemilikan, ownership bernilai null. Ikhtisar Numbers menjelaskan arti setiap status. Untuk mengajukan dokumen kepemilikan yang masih ditunggu suatu nomor, lihat Mengajukan dokumen kepemilikan nomor.

Setiap entri juga memuat pricing, yaitu jumlah yang dibayar organisasi Anda untuk nomor tersebut, sebelum pajak:

recurring_price adalah tarif Anda per recurring_period, dalam mata uang yang digunakan untuk menagih nomor tersebut. Itu adalah mata uang penagihan Anda, kecuali langganan nomor dimulai sebelum mata uang penagihan Anda berubah; nomor seperti itu tetap memakai mata uang langganannya, yang disebutkan oleh currency_code.
intervals_per_charge adalah jumlah recurring_period yang ditagih satu perpanjangan. Biaya berulang sebelum pajak adalah recurring_price dikalikan intervals_per_charge. Harga tetap untuk nomor tersebut mencakup seluruh periodenya, sehingga intervals_per_charge bernilai 1.

pricing bernilai null untuk nomor shared dan untuk nomor tanpa langganan aktif. Jika langganan nomor tidak memiliki harga yang berlaku, harganya bernilai null dengan pricing.error: null; hubungi tim penjualan agar nomor tersebut diberi harga. Jika harga tidak dapat dibaca, pricing.error berisi E14009 dan harganya bernilai null. Coba lagi GET /v1/numbers/{number_id} dengan exponential backoff. Nomor tersebut tetap tersedia untuk dikelola; jangan mengulangi pembaruan atau pembatalan yang sudah selesai untuk menyegarkan harganya.

Dashboard dan API menggunakan resolusi harga yang sama. Harga tetap mempertahankan ketentuannya yang ada; selain itu, yang ditampilkan adalah tarif saat ini, yang dapat berubah sebelum perpanjangan. Resolusi ini tidak melaporkan harga yang dikenakan oleh pesanan sebelumnya. Nomor dengan releases_at yang terisi mempertahankan pricing-nya hingga dilepas, dan tidak ada perpanjangan setelahnya.

Temukan nomor dalam daftar Anda

Filter daftar saling digabungkan, jadi filter negara atau kemampuan tetap berlaku bersama filter lainnya.

number mencari satu nomor apa pun format yang Anda gunakan. +31612345678 dan 0031612345678 mengarah ke nomor yang sama. Format nasional seperti 0612345678 hanya dapat ditemukan jika country_code menyebutkan negaranya:

Contoh kode

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

Jika Anda memasukkan nomor lengkap, atau format nasional beserta country_code-nya, tanpa filter lain, array data yang kosong berarti nomor tersebut tidak dialokasikan ke workspace Anda, termasuk nomor yang sudah Anda lepas. Format nasional tanpa country_code, misalnya 0612345678 saja, juga mengembalikan daftar kosong, jadi hasil tersebut tidak membuktikan bahwa nomor itu bukan milik Anda.

search mencocokkan sebagian nomor, nama, atau referensinya, tanpa membedakan huruf besar-kecil. reference mengembalikan nomor dengan referensi yang persis sama, dengan membedakan huruf besar-kecil:

Contoh kode

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix mengembalikan nomor yang diawali digit yang Anda berikan, dan arti digit tersebut bergantung pada country_code:

Dengan country_code, digit yang dicocokkan adalah digit nasional, tepat setelah kode panggil. prefix=6&country_code=NL mengembalikan nomor Belanda yang diawali +31 6.
Tanpa country_code, digit dicocokkan dari awal nomor lengkap. prefix=6 saja mengembalikan nomor yang kode panggilnya diawali 6, seperti nomor +61 Australia, sehingga tidak menemukan nomor ponsel Belanda Anda. Filter ini juga mencocokkan short code yang diawali digit tersebut.

Beri nama nomor dan atur referensi Anda

Setiap nomor membawa dua label milik Anda. name membedakan nomor-nomor Anda, misalnya Support line. reference menyimpan pengidentifikasi dari catatan Anda sendiri, seperti id pelanggan atau toko, dan tidak harus unik. Keduanya berlaku untuk nomor dedicated maupun shared dan maksimal 100 karakter.

Atur keduanya dengan PATCH /v1/numbers/{number_id}. Field yang tidak Anda sertakan mempertahankan nilainya saat ini, dan field yang Anda kirim sebagai null akan dikosongkan. Spasi di awal dan akhir dihapus secara otomatis.

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

Responsnya adalah 200 dengan nomor yang telah diperbarui. Untuk menghapus referensi dan mempertahankan nama, kirim referensi sebagai null dan jangan sertakan nama:

Contoh kode

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

Untuk menetapkan referensi saat Anda membeli nomor, sertakan reference pada POST /v1/numbers/orders. Pesanan yang harus menunggu operator tetap menyimpan referensi hingga nomor dialokasikan, dan nomor tersebut membawanya sejak saat itu.

Menemukan voice record yang merutekan nomor

Nomor yang memiliki voice punya dua identifier. id pada GET /v1/numbers diawali dengan nda_ untuk nomor dedicated dan nal_ untuk nomor shared, dan operasi numbers menerimanya. Operasi voice, termasuk yang mengatur tujuan panggilan masuk, menerima voice record nomor tersebut, yang id-nya diawali dengan vnu_. Mengirim id nda_ atau nal_ ke operasi voice ditolak dengan 422.

Untuk berpindah dari satu ke yang lain, cari voice numbers berdasarkan nomor telepon. Ini memerlukan cakupan voice_management di level read:

Contoh kode

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

id pada entri tersebut adalah identifier vnu_, dan provider.number_id-nya adalah identifier nda_ atau nal_ dari nomor yang sama. Menerima panggilan menunjukkan cara merutekan nomor dari sana.

Voice record memiliki name tersendiri. Memberi nama nomor dengan PATCH /v1/numbers/{number_id} tidak mengubah nama voice record, dan sebaliknya.

Melepas nomor

Anda dapat mengembalikan nomor dedicated dengan dua cara:

Di akhir periode yang telah Anda bayar. DELETE /v1/numbers/{number_id} menghentikan perpanjangan nomor. Nomor tetap berfungsi hingga periode penagihan saat ini berakhir, lalu dilepas. Respons 202 mengembalikan nomor dengan releases_at disetel ke waktu tersebut, dan permintaan ulang mengembalikan releases_at yang sama. Pembatalan tidak dapat dibatalkan. Nomor tanpa langganan di belakangnya, misalnya nomor yang dialokasikan kepada Anda tanpa biaya, langsung dilepas, dan responsnya adalah 200 dengan status nomor disetel ke released.
Sekarang. POST /v1/numbers/{number_id}/release melepas nomor segera, termasuk nomor yang sudah dijadwalkan untuk dibatalkan. Sisa periode saat ini tidak dikembalikan. Membeli dan melepas nomor menunjukkan panggilan tersebut di setiap SDK.

Selama pembayaran perpanjangan untuk nomor tersebut tertunggak, kedua permintaan menjawab 409 hingga dibayar.

Opsi pelepasan mana pun yang Anda pilih, kirim permintaan dengan Idempotency-Key agar percobaan ulang aman: kunci yang sama memutar ulang respons pertama dengan header Idempotency-Replay: true, sedangkan permintaan baru untuk nomor yang sudah dilepas menjawab 404 dengan E01008. Idempotency menjelaskan berapa lama kunci disimpan.

Selama pembatalan terjadwal belum berlaku, nomor tetap terbaca seperti biasa dan membawa releases_at. Setelah pelepasan:

Nomor berhenti berfungsi untuk Anda, dan langganannya tidak diperpanjang.
GET /v1/numbers/{number_id} dan voice record nomor tersebut menjawab 404, dan nomor tersebut keluar dari GET /v1/numbers.
Pesanan nomor tetap ada di GET /v1/numbers/orders, dan number_id-nya sekarang menjawab 404.
Nomor masuk ke masa tunggu 30 hari sebelum dapat kembali dijual, sehingga Anda tidak bisa langsung membeli kembali nomor yang sama.

Langkah selanjutnya

Menerima panggilan merutekan nomor ke trunk SIP, penerusan, atau urutan.
Membeli dan melepas nomor memandu proses pembelian melalui API.
Referensi API Numbers mendokumentasikan setiap operasi dan field.

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

Dapatkan ringkasan implementasi

Mengelola nomor telepon Anda

Daftar semua nomor yang Anda miliki

Temukan nomor dalam daftar Anda

Beri nama nomor dan atur referensi Anda

Menemukan voice record yang merutekan nomor

Melepas nomor

Langkah selanjutnya

Sumber daya terkait