Migrasi dari Telserv ke Bird

Panduan ini ditujukan untuk integrasi yang memanggil API partner Telserv, V1 atau V2, untuk membeli, merutekan, dan melepas nomor, dan yang sekarang berpindah ke Bird API.

Bird API melayani setiap produk Bird, sehingga operasi nomor dan suaranya mengikuti konvensi Bird sendiri, bukan konvensi Telserv. Sebagian besar kemampuan yang digunakan integrasi Anda memiliki panggilan Bird. Endpoint, payload, identifier, dan autentikasi berbeda, jadi rencanakan untuk menulis ulang integrasi tersebut. Jika Bird melakukan suatu pekerjaan dengan cara berbeda, panduan ini menunjukkan caranya.

Panduan ini masih dalam pengembangan. Panduan ini mencakup apa yang dilakukan Bird saat ini, dan bertambah seiring berjalannya migrasi. Jika operasi Telserv yang Anda gunakan belum tercantum di sini, operasi tersebut masih perlu pelingkupan dan pengerjaan sebelum dapat ditambahkan; tanyakan kepada kontak migrasi Anda.

Sebelum Anda mulai

• Organisasi Bird dengan verifikasi identitas yang sudah selesai, yang diperlukan untuk pembelian nomor pertama.
• Kunci API dengan scope yang digunakan resep ini: numbers pada level tulis untuk nomor dan order, compliance pada level tulis untuk operasi dokumen kepemilikan yang berdiri sendiri, dan voice_management pada level tulis untuk trunk SIP, nomor suara, dan nomor terverifikasi. Panggilan uji juga memerlukan voice:write, dan membaca leg panggilan memerlukan voice:read.
• Saldo wallet. Order dibayar dari wallet. Ketika order ditolak menjelaskan penolakan 402 dan 412.

Nomor yang dikelola integrasi Anda di Telserv tidak perlu dibeli ulang. Setelah nomor Anda dipindahkan ke workspace Bird Anda, nomor tersebut muncul di GET /v1/numbers. Kontak migrasi Anda mengonfirmasi kapan hal itu terjadi. Untuk mendapatkan identifier nda_ dari nomor yang dipindahkan, cari nomor tersebut dengan GET /v1/numbers?number=<digits>, berikan digitnya beserta kode negara, dan simpan id sebagai NUMBER_ID.

Contoh-contoh ini membaca kunci Anda dari BIRD_API_KEY dan host regional-nya dari BIRD_API_URL: https://eu1.platform.bird.com untuk kunci bk_eu1_, atau https://us1.platform.bird.com untuk kunci bk_us1_. Variabel lainnya, seperti TRUNK_ID dan NUMBER_ID, menyimpan identifier dari respons sebelumnya; setiap langkah menyebutkan identifier yang ditetapkannya.

Apa yang berubah dalam kontrak

Bird API menolak parameter kueri yang tidak dikenali dengan 422 dan E01029. Hapus filter khusus Telserv seperti city dari permintaan Anda, jangan meneruskannya begitu saja.

Dua identifier untuk satu nomor

Nomor berkemampuan suara yang dialokasikan ke workspace Anda memiliki dua rekaman, masing-masing dengan identifier sendiri:

• Alokasi, dikembalikan oleh GET /v1/numbers. id-nya diawali nda_ untuk nomor khusus dan nal_ untuk nomor bersama, dan number_id pada pesanan adalah identifier nda_ dari nomor yang dibelinya. Gunakan untuk membaca, memberi nama, dan mereferensikan nomor, serta untuk melepas nomor khusus.
• Rekaman suara, vnu_, dikembalikan oleh GET /v1/voice/numbers. Gunakan untuk membaca dan mengubah tujuan panggilan masuk nomor tersebut. Nomor tanpa kemampuan suara, seperti nomor khusus SMS, tidak memiliki rekaman suara.

Operasi suara menolak identifier nda_ atau nal_ dengan 422. Untuk menemukan rekaman suara sebuah nomor, tampilkan daftar nomor suara dengan search disetel ke digit nomor tersebut dan ambil entri yang provider.number_id-nya sama dengan id alokasi. Rutekan nomor ke trunk SIP Anda menunjukkan permintaannya, dan Mengelola nomor telepon Anda membahas pencarian tersebut.

GET /numbers/{dnisId} milik Telserv menjadi dua pembacaan di Bird: alokasi untuk status dan dokumen kepemilikan, dan rekaman suara untuk rute.

Petakan operasi Telserv ke Bird

Setiap tabel mencantumkan pekerjaan, panggilan Telserv yang melakukannya, dan panggilan Bird yang melakukannya sekarang. Catatan di bawah setiap tabel membahas perubahan pada permintaan atau responsnya.

Belanja

• Pencarian. country_code wajib diisi, sehingga satu pencarian mencakup satu negara. prefix menerima digit nasional setelah kode negara: Telserv prefix=3170 menjadi country_code=NL&prefix=70. Persempit berdasarkan kode area dengan prefix sebagai pengganti city, dan berdasarkan number_type serta capabilities sebagai pengganti productId.
• Dokumen kepemilikan dalam hasil pencarian. Setiap hasil memuat ownership_registration_required sebagai pengganti filter excludeNumbersRequireVerification. Nilai true berarti nomor ditagih sejak pembelian, tetapi tidak mengirim SMS dan tidak membawa panggilan suara masuk maupun keluar sampai dokumennya disetujui.
• Periksa satu nomor. Nomor diakses berdasarkan nomor E.164-nya.
• Harga. Telserv mengembalikan pricing.staticPricing pada pembacaan detail nomor dan produk. Di Bird, setiap hasil pencarian memuat harga untuk organisasi Anda di pricing: setup_price sebagai pengganti nrc, dan recurring_price per recurring_period sebagai pengganti mrc, dengan intervals_per_charge untuk jumlah periode yang dicakup satu tagihan. Cari dan beli nomor dengan referensi Anda menjelaskan kolom harga.
• Beli. Kirim number dan opsional reference. Pesanan dibayar dari wallet Anda. Sebagian besar pesanan menjawab 201; pesanan yang menunggu operator menjawab 202, dan Anda melakukan polling.
• Amankan. Memesan nomor langsung mengamankannya. Periksa kandidat terlebih dahulu, lalu pesan.

Nomor

• Daftar. Daftar ini berisi nomor yang dialokasikan untuk Anda saat ini. Nomor yang sudah dilepas dan Anda pesan di Bird tetap terlihat melalui pesanannya di GET /v1/numbers/orders. Rekonsiliasi nomor Anda memetakan filter-filternya.
• Baca. Status, dokumen kepemilikan, dan harga ada di alokasi, sedangkan rute ada di rekaman suara. Objek pricing pada alokasi, dengan recurring_price per recurring_period dan intervals_per_charge, menggantikan pricing.staticPricing.mrc, dan daftar juga menyertakannya, sedangkan GET /numbers milik Telserv tidak.
• Ubah. name dan reference ada di alokasi, sedangkan rute ada di rekaman suara. Atur codec paksa dan batas panggilan bersamaan di peralatan SIP Anda. destinationDistributionType menjadi gateway priority di trunk SIP: FailOver memberikan setiap gateway priority yang berbeda, dan RoundRobin memberikan nilai yang sama kepada semuanya.
• Lepas. DELETE mempertahankan nomor hingga akhir periode yang sudah Anda bayar, lalu melepasnya. POST …/release melepasnya langsung. Keduanya tidak menerima tanggal. Melepas nomor menampilkan kedua permintaan.

Tujuan dan profil

• Peralatan SIP. Gateway menjadi bagian dari trunk dan melayani setiap nomor yang dirutekan ke sana, sehingga nomor yang membutuhkan daftar tujuan berbeda memerlukan trunk berbeda. sortOrder menjadi priority. Terapkan waktu dering dan jendela waktu pada peralatan SIP Anda.
• Teruskan. Atur forward_to dan forward_as. forward_to harus berupa salah satu nomor terverifikasi Anda; nomor yang belum diverifikasi menjawab 412 dengan E21053. forward_as menentukan nomor mana yang ditampilkan sebagai penelepon pada panggilan yang diteruskan. Satu nomor hanya memiliki satu rute pada satu waktu, jadi untuk beralih dari peralatan SIP ke nomor telepon, teruskan panggilan dari peralatan SIP Anda.
• Berhenti menerima panggilan. Nomor menolak panggilan sampai Anda merutekannya kembali. Untuk mempertahankan default tetap sebagai pengganti profil default, rutekan nomor ke trunk yang memuat gateway default Anda.
• Profil. distributionType menjadi priority: FailOver memberikan setiap gateway priority yang berbeda, dan RoundRobin memberikan nilai yang sama kepada semuanya. Distribusi diatur per trunk, jadi nomor yang membutuhkan distribusi berbeda memerlukan trunk berbeda. Placeholder {dnis} menjadi {number} di destination_format, dan prefixCLIP menjadi teks sebelum {number} di origination_format.
• Terapkan profil. Trunk dialamatkan berdasarkan identifier spt_-nya, sedangkan Telserv mengalamatkan profil berdasarkan nama.

Dokumen dan data pengguna akhir

• Persyaratan. Katalog persyaratan Telserv mencakup semua produk sekaligus; Bird membaca satu formulir setiap kali. Minta persyaratan satu nomor dengan subject_kind=number, identifier nda_-nya sebagai subject_id, dan country_code-nya, atau baca formulir sebelum membeli dengan program diisi jenis nomor dan tanpa subject_id. Setiap entri di fields menggantikan satu persyaratan atau label pengguna akhir Telserv: key-nya adalah kunci tempat Anda menjawab, dan data_type document menandai entri yang memerlukan file.
• Dokumen. Unggah file sebagai multipart/form-data, bukan fileContent base64; Unggah setiap dokumen mencantumkan file yang diterima. Mengunggah file yang sama dua kali mengembalikan lampiran yang sama. Unggahan saja tidak mengajukan apa pun: pengajuan yang merujuk attachment_id-nya yang mengajukannya.
• Data pengguna akhir dan dokumen sekaligus. Telserv menerima setiap dokumen dalam panggilan tersendiri, dan data pengguna akhir sebagai satu daftar label dalam panggilan lain. Bird menerima semua jawaban, baik isian maupun dokumen, dalam satu pengajuan, dan tidak ada draf: permintaan tersebut langsung mengajukan jawaban untuk ditinjau. Setelah itu, ikuti ownership.next, yang menyebutkan resupply untuk koreksi dan pengajuan baru hanya jika diperlukan (Ajukan semua jawaban).
• Penggantian. Kirim hanya jawaban yang Anda ganti, dan jawaban lainnya mempertahankan status tinjauannya. Telserv menerima file baru untuk suatu persyaratan selama nomor menunggu verifikasi, dan file itu mengatur ulang tinjauan persyaratan tersebut; Bird mengganti jawaban yang ditolak, kedaluwarsa, atau belum diberikan, dan menolak jawaban yang masih ditinjau atau sudah diterima, kecuali jawaban bertanda editable_for_verifier_repair selama koreksi yang kami minta masih terbuka (Koreksi jawaban yang ditolak).
• Progres. ownership.status dan ownership.next melaporkan posisi nomor tersebut. Setiap jawaban memiliki state sendiri, dan jawaban yang ditolak menyertakan reason dari peninjau. Bird juga mengirim email berisi setiap hasil kepada pemilik organisasi Anda dan kepada orang yang terakhir mengajukan atau mengoreksi pengajuan. ownership biasanya null jika nomor tidak memerlukan dokumen.

Ajukan dokumen kepemilikan menampilkan permintaannya, dan Mengajukan dokumen kepemilikan nomor membahas seluruh alurnya, termasuk pengajuan dari dashboard dan bersama pesanan.

Produk dan data master

Setiap hasil pencarian menjelaskan produknya dengan number_type, capabilities, dan ownership_registration_required, serta menyertakan harga untuk organisasi Anda sebagai pengganti pricing.staticPricing produk (nrc dan mrc). Harga standar Bird ada di halaman harga nomor telepon. sessionPricing per menit dari Telserv tidak memiliki padanan di pembacaan ini; tarif suara ada di halaman harga suara.

Tipe nomor Telserv dipetakan ke number_type milik Bird seperti berikut:

Yang bekerja secara berbeda

Pekerjaan Telserv berikut dilakukan secara berbeda di Bird. Rencanakan sebelum Anda memindahkan integrasi yang bergantung pada salah satunya.

• Dokumen kepemilikan. Ajukan dokumen dan data pengguna akhir sebuah nomor dalam satu pengajuan, tanpa draf, dan perbaiki jawaban yang ditolak dengan resupply.
• Reservasi. Pesan nomor setelah Anda memilihnya; pesanan mengamankan nomor tersebut.
• Pengaturan panggilan per nomor. Terapkan codec paksa, batas panggilan bersamaan, waktu dering, dan jendela waktu pada peralatan SIP Anda.
• Tanggal pelepasan. Bird melepaskan nomor di akhir periode yang sudah dibayar atau langsung, bukan pada tanggal yang Anda pilih. Simpan tanggal pembatalan yang Anda kirim ke Telserv di sisi Anda, dan tindak lanjuti masing-masing saat jatuh tempo.
• Saldo wallet. Periksa saldo dan isi ulang di dashboard.

Cari dan beli nomor dengan referensi Anda

Cari satu negara. Kombinasikan number_type, capabilities, dan prefix untuk mempersempit hasil:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Setiap hasil memuat objek pricing dengan harga yang dibayar organisasi Anda untuk nomor tersebut, sebelum pajak dan dalam mata uang penagihan Anda, dengan harga yang Anda sepakati bersama Bird sudah diterapkan:

• setup_price dikenakan sekali saat Anda memesan nomor. Biaya yang dipublikasikan sebesar nol memiliki amount bernilai "0". Field itu sendiri bernilai null jika tidak ada biaya pemasangan, dan juga setiap kali recurring_price bernilai null, karena nomor tersebut tidak dapat dipesan.
• recurring_price adalah tarif per recurring_period.
• intervals_per_charge adalah jumlah recurring_period yang dicakup satu tagihan. Biaya berulang sebelum pajak adalah recurring_price dikalikan intervals_per_charge, dikenakan saat nomor ditetapkan ke workspace Anda dan pada setiap perpanjangan; biaya pemasangan terpisah. Untuk pesanan yang menunggu operator, penetapan terjadi saat pesanan selesai.

Referensi API menampilkan contoh hasil. Hasil dengan pricing.recurring_price: null tidak memberikan harga berulang. Hubungi tim penjualan agar negara dan jenis nomor tersebut diberi harga untuk Anda sebelum memesan.

Dashboard dan API menggunakan harga organisasi yang sama, termasuk konversi ke mata uang penagihan Anda. Pembacaan harga tidak mengunci kuotasi: perubahan tarif atau nilai tukar sebelum tagihan berikutnya dapat mengubah jumlahnya. Jika pencarian harga gagal, hasil pencarian mengembalikan 503 dengan E14009. Coba lagi pembacaan dengan exponential backoff; kegagalan pencarian harga tidak pernah berarti nomor tersebut tidak dikenai biaya.

Untuk mengonfirmasi kandidat dan harganya sebelum Anda memesannya, baca dengan GET /v1/numbers/available/{number}. Respons 404 berarti nomor tersebut sudah tidak dijual.

Pesan nomor dengan referensi yang Anda gunakan di Telserv, dan pilih kunci idempotensi yang Anda simpan untuk percobaan ulang pembelian ini:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

Respons 201 memiliki status: completed dan sebuah number_id, identifier nda_ nomor tersebut. Simpan sebagai NUMBER_ID. Respons 202 berarti pesanan menunggu operator: polling pesanan sampai status-nya menjadi completed atau failed. Biaya pemasangan yang sudah dikenakan tidak dikembalikan jika pesanan kemudian gagal. Referensi ditetapkan pada nomor saat pesanan selesai. Referensi menampung hingga 100 karakter dan tidak harus unik.

Mencoba lagi pesanan untuk nomor yang sudah dialokasikan ke workspace Anda mengembalikan pesanan yang sudah ada, sehingga percobaan ulang tidak menagih dua kali. Membeli dan melepas nomor menjelaskan penolakan-penolakannya.

Untuk menetapkan atau mengubah referensi nanti, kirim reference (dan opsional name) ke PATCH /v1/numbers/{number_id}. Kirim null untuk mengosongkan field.

Periksa bahwa nomor dapat membawa panggilan

Nomor yang status-nya pending_ownership_registration sudah dialokasikan dan ditagih, tetapi tidak mengirim SMS dan menolak panggilan suara masuk dan keluar sampai dokumen kepemilikannya disetujui. Sebelum Anda merutekan nomor atau melakukan panggilan uji ke nomor tersebut, baca nomor itu dengan GET /v1/numbers/{number_id} dan periksa bahwa status bernilai active. Jika statusnya masih tertunda, ajukan dokumen kepemilikan. Status nomor yang dialokasikan menjelaskan setiap nilai.

Contoh-contoh di bawah menggunakan nomor ponsel Belanda. Periksa status nomor Anda sendiri dengan cara yang sama, apa pun negaranya.

Ajukan dokumen kepemilikan

Telserv menerima dokumen kepemilikan nomor dengan satu POST /numbers/{dnisId}/documents per dokumen dan satu POST /numbers/{dnisId}/enduserdata untuk semua label. Bird menerima keduanya dalam satu pengajuan, setelah Anda mengunggah dokumennya.

1. Baca country_code nomor tersebut dan simpan sebagai COUNTRY_CODE. Perintah ini mengekstraknya dengan jq; baca secara manual jika Anda tidak menggunakan jq:

   Contoh kode

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Baca apa yang diminta negara nomor tersebut. Setiap entri di fields memiliki key yang menjadi tempat jawaban Anda, sebuah data_type, dan required, yang menunjukkan apakah Anda wajib menjawabnya. Simpan program yang disebutkan respons sebagai PROGRAM:

   Contoh kode

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   Respons 422 dengan E19001 berarti tidak ada formulir kepemilikan untuk negara tersebut.

3. Unggah setiap dokumen yang diminta field document, sebagai file, bukan base64 fileContent. Simpan id dari respons, yaitu identifier tca_ lampiran, sebagai ATTACHMENT_ID:

   Contoh kode

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Kirim semua jawaban sekaligus: satu entri untuk setiap field yang required-nya true, dan untuk setiap field opsional yang benar-benar Anda miliki jawabannya, dengan data pengguna akhir sebagai value dan setiap dokumen sebagai attachment_id. Biarkan field opsional kosong daripada mengarang nilainya. Contoh ini menampilkan dua jawaban; tambahkan jawaban wajib lainnya sebelum mengirim. Permintaan ini mengajukan jawaban untuk ditinjau. Simpan id dari respons, yaitu identifier csb_ pengajuan, sebagai SUBMISSION_ID:

   Contoh kode

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   Respons 201 mengembalikan pengajuan. Respons 422 tidak mengajukan apa pun: perbaiki body dan kirim dengan kunci idempotensi baru, karena kunci lama akan memutar ulang penolakan tersebut. Kirim semua jawaban menjelaskan setiap penolakan.

5. Jika peninjau menolak suatu jawaban, ganti hanya jawaban tersebut, seperti dijelaskan di Perbaiki jawaban yang ditolak:

   Contoh kode

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Untuk mengajukan dokumen sekaligus saat membeli, kirim answers yang sama di blok compliance pada POST /v1/numbers/orders. Pesanan tersebut menggunakan scope numbers yang sudah ada pada level tulis, termasuk saat pesanan memuat dokumen kepemilikan.

Pantau peninjauan dengan ownership.status pada GET /v1/numbers/{number_id}. Jawaban tersebut merupakan pernyataan hukum yang dibuat atas nama bisnis Anda, jadi ajukan hanya jawaban yang sudah dikonfirmasi oleh orang yang bertanggung jawab atasnya. Ajukan dokumen kepemilikan nomor membahas setiap permintaan, peninjauan, dan pengajuan bersama pesanan.

Rutekan nomor ke trunk SIP Anda

Nomor baru tidak memiliki rute sendiri, sehingga mengikuti rute default workspace Anda. Rute default itu awalnya reject, tetapi di workspace yang sudah menetapkannya, nomor baru menjawab panggilan sesuai rute tersebut begitu nomor dialokasikan. Untuk mengirimkan panggilannya ke peralatan Anda, buat trunk SIP dengan panggilan masuk aktif, tambahkan gateway, dan arahkan nomor ke trunk tersebut. Trunk SIP membahas cara menghubungkan peralatan Anda ke trunk.

1. Buat trunk dengan panggilan masuk aktif. Simpan id dari respons, yaitu identifier spt_ trunk, sebagai TRUNK_ID:

   Contoh kode

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. Tambahkan gateway. Secara default, gateway menerima nomor tujuan dan nomor pemanggil dalam format E.164 dengan +. Jika perangkat Anda mengharapkan nomor tanpa +, seperti yang dilakukan placeholder {dnis} Telserv, atur destination_format untuk nomor tujuan dan origination_format untuk nomor pemanggil ke {number}:

   Contoh kode

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   Untuk failover, tambahkan gateway kedua; Yang dibutuhkan gateway menjelaskan priority dan format nomor. Membuat gateway yang sama lagi tanpa kunci idempotensi menghasilkan respons 409 dengan E21047.

3. Temukan rekaman suara nomor tersebut. Cari dengan digit nomor dan ambil id dari entri yang provider.number_id-nya adalah id alokasi. Simpan sebagai VOICE_NUMBER_ID:

   Contoh kode

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Arahkan nomor ke trunk:

   Contoh kode

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   Respons 200 menampilkan rute baru. Trunk dengan panggilan masuk nonaktif menjawab 412 dengan E21052.

Menonaktifkan panggilan masuk pada trunk, atau menghapus trunk, mengembalikan setiap nomor yang diarahkan ke trunk tersebut ke rute default workspace Anda, dan mengaktifkannya kembali tidak memulihkan rute-rute tersebut. Kirim panggilan ke trunk SIP menjelaskan hal ini serta rute trunk, forward, dan reject.

Rekonsiliasi nomor Anda

Telusuri daftar dengan ukuran halaman terbesar. Kirim next_cursor setiap halaman sebagai NEXT_CURSOR untuk membaca halaman berikutnya, sampai next_cursor bernilai null. Daftar tidak mengembalikan jumlah total.

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Filter daftar Telserv dipetakan ke filter Bird seperti ini:

Temukan nomor di daftar Anda membahas setiap filter secara detail.

Setiap entri memuat pricing, dengan recurring_price per recurring_period dan intervals_per_charge. Kecuali harga ditetapkan untuk nomor tersebut, recurring_price adalah tarif organisasi Anda saat ini, dan setiap perpanjangan mengenakan tarif yang berlaku saat diperpanjang, sehingga tagihan yang sudah dikenakan bisa berbeda dari tarif tersebut. Daftar semua nomor yang Anda miliki menjelaskan mata uang yang digunakan untuk menagih setiap nomor, kapan pricing atau harganya bernilai null, dan apa yang harus dilakukan jika pricing.error terisi.

Nomor yang sudah dilepas tidak lagi muncul di daftar ini, dan membacanya berdasarkan number_id menghasilkan 404. Jika Anda memesannya di Bird, pesanan yang sudah selesai tetap ada di GET /v1/numbers/orders.

Melepas nomor

Kedua permintaan berlaku untuk nomor khusus, berdasarkan identifier nda_-nya; nomor bersama ditolak dengan E14002. Untuk mempertahankan nomor hingga akhir periode yang sudah Anda bayar, batalkan nomor tersebut:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Respons 202 mengembalikan nomor dengan releases_at, yaitu akhir periode yang sudah dibayar. Nomor mempertahankan statusnya saat ini hingga saat itu, langganannya tidak diperpanjang, dan nomor dilepas pada waktu tersebut. Permintaan ulang mengembalikan releases_at yang sama, dan pembatalan tidak dapat dibatalkan. Nomor yang tidak memiliki langganan langsung dilepas, dan responsnya adalah 200 dengan status nomor disetel ke released.

Untuk melepas nomor sekarang, termasuk nomor yang sudah dijadwalkan untuk pembatalan:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Respons 204 berarti nomor telah dilepas, berlaku segera. Sisa periode saat ini tidak dikembalikan.

Selama pembayaran perpanjangan untuk nomor tersebut tertunggak, kedua permintaan menjawab 409 dengan E03015 sampai pembayaran dilunasi.

Tidak satu pun permintaan menerima tanggal, jadi simpan jadwal yang Anda kirim ke Telserv sebagai requestedCancelDate di sisi Anda. Untuk mempertahankan nomor hingga tanggalnya, batalkan nomor tersebut setelah tanggal jatuh dalam periode penagihan saat ini: nomor dilepas saat periode itu berakhir, pada atau setelah tanggal tersebut. Untuk melepasnya tepat pada tanggal itu, lepaskan nomor pada hari itu. Melepas nomor menjelaskan apa yang dilakukan setiap permintaan terhadap nomor, tagihannya, dan percobaan ulang.

Lakukan panggilan uji ke nomor Anda

Untuk memeriksa rute secara menyeluruh, lakukan panggilan ke nomor tersebut dari nomor lain yang boleh ditampilkan workspace Anda sebagai caller ID. Negara nomor tersebut harus diaktifkan di tujuan panggilan suara Anda, atau panggilan tidak akan terhubung. Permintaan di bawah menjalankan urutan inline yang menutup panggilan begitu dijawab, sehingga tidak perlu urutan tersimpan. Panggilan ini adalah panggilan nyata, dan biaya panggilan normal berlaku.

Simpan permintaan sebagai test-call.json. Masukkan caller ID yang Anda tampilkan di from, yaitu nomor milik atau nomor terverifikasi workspace Anda, dan nomor yang diuji di to:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

Kirim:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

Atur TEST_CALL_KEY ke nilai baru untuk setiap pengujian, dan gunakan kembali saat Anda mencoba lagi pengujian yang sama setelah timeout atau hasil yang tidak jelas: kunci dan permintaan yang sama dalam tiga jam akan memutar ulang penerimaan pertama alih-alih melakukan panggilan kedua. Respons 202 menerima panggilan dan mengembalikan initial_leg_id-nya. Penerimaan tidak membuktikan panggilan terhubung: baca leg dengan GET /v1/voice/legs/{leg_id}, atau tampilkan daftar leg yang dilakukan ke nomor tersebut dengan GET /v1/voice/legs dan filter to-nya, lalu periksa bahwa peralatan Anda menerima panggilan tersebut. Membuat panggilan suara membahas persyaratan caller ID dan tujuan serta aturan percobaan ulang.

Langkah selanjutnya

• Membeli dan melepas nomor
• Mengelola nomor telepon Anda
• Ajukan dokumen kepemilikan nomor
• Menerima panggilan
• Trunk SIP
• Idempotensi