Migrasi SMS dari Bandwidth
Halaman ini memetakan Messages API, Applications, dan callback pesan Bandwidth ke Bird. Ikuti panduan migrasi utama secara berurutan dan gunakan pemetaan ini untuk langkah 3, 4, dan 5.
Dua perbedaan membentuk keseluruhan proses porting. Bandwidth membagi channel ke dua host: pengiriman berada di host messaging di bawah path akun Anda, diautentikasi melalui HTTP Basic, sementara registrasi 10DLC berada di host utama API. Bird menempatkan pengiriman, registrasi, dan event pengiriman di bawah satu base URL dan satu bearer key. Dan applicationId pada setiap pengiriman Bandwidth membawa konfigurasi callback; Bird tidak memiliki objek yang setara, karena callback adalah subscription workspace, bukan properti dari pesan.
Berikan ini ke agen Anda
Gunakan ringkasan ini di coding agent Anda. Prosesnya dimulai dengan penemuan dan menghasilkan rencana migrasi yang dapat ditinjau sebelum ada perubahan di produksi.
Contoh kode
Help me migrate my SMS integration from Bandwidth to Bird.
1. Inspect this repository's sends, senders, callbacks, schedules, templates, opt-outs and tests. List the traffic and behavior that must survive the migration.
2. Read the Markdown guides at https://bird.com/docs/guides/sms/migrate/bandwidth.md and https://bird.com/docs/guides/sms/migrate.md. Use an existing authenticated Bird MCP or CLI connection. If neither is available, follow https://bird.com/docs/ai/set-up-your-agent.md. Discover the actual operations; do not invent commands or ask me to paste credentials into chat.
3. Prepare the code changes, sender/destination requirements, consent migration, webhook verification and rollout/rollback plan. Preserve the scope of each customer's preferences, including requests outside SMS replies. Separate API batches from audience broadcasts and preserve any behavior that has no direct endpoint equivalent.
4. Show me the exact affected resources, destinations, test volume and known costs before an action that sends messages, spends money, registers or changes a sender, or moves production traffic. Require explicit human authorization for each paid submission or production change. Name one-off 10DLC registration and resubmission fees before requesting approval. An existing explicit approval for that exact action is sufficient; broad migration approval is not. Simulated SMS destinations are billable and still require authorization.
5. If I am keeping Bandwidth numbers, prepare the human support port request and obtain authorization to send it. Read bird support-tickets create --help, then use the available CLI or MCP support operation with the reviewed number list and requirements. Return the ticket ID and follow the reply; support arranges the port on its own schedule, separately from the code cutover.
6. Run local and intercepted tests first. When authorized, perform the agreed bounded integration tests, inspect accepted and final outcomes separately, and report failures or uncertainty. Do not claim a delivery receipt proves reading or that request idempotency guarantees exactly-once delivery.
7. Keep production cutover and retiring the old provider as explicit steps in the approved rollout. Finish with the diff, evidence, unresolved requirements and the next action.Petakan panggilan pengiriman
| Fungsi | Bandwidth | Bird |
|---|---|---|
| Penerima | to (array) | to (satu per permintaan) |
| Pengirim | from | from |
| Isi | text | text |
| Routing callback | applicationId | webhook workspace yang di-subscribe ke event pengiriman di bawah |
| Intent | (tidak ada) | category, wajib pada teks bebas |
| Label bebas | tag (satu string) | metadata; tags hanya jika Anda dapat menamainya |
| Konteks round-trip | penyimpanan Anda sendiri, dikunci berdasarkan ID | metadata: JSON arbitrer, dikembalikan pada setiap event |
| Prioritas pengiriman | priority | tidak ada padanannya |
| Percobaan ulang aman | (tidak ada dalam spesifikasi mereka) | header Idempotency-Key |
| Media | media | tidak ada padanannya: media_urls ditolak |
Catatan porting:
- to berubah dari array menjadi satu penerima. Bandwidth menerima daftar; Bird mengirim satu pesan per permintaan. Loop menggantikan array, dan setiap panggilan dapat membawa Idempotency-Key sendiri.
- applicationId hilang, bukan dipindahkan. Objek ini ada untuk memberi tahu Bandwidth ke mana callback dikirim. Di Bird, itu adalah subscription workspace, jadi tidak ada yang menyebutkannya pada pengiriman.
- tag dan tags bukan field yang sama. tag milik Bandwidth adalah satu string bebas; tags milik Bird adalah pasangan {name, value} yang menjadi dimensi kueri. Satu string opak biasanya lebih baik dimasukkan ke metadata.
- Tidak ada yang pada Messages API berpadanan dengan category. Tentukan per tipe pesan apakah itu transactional, marketing, authentication, atau service.
Migrasikan opt-out
Tidak ada daftar yang bisa diekspor, dan itulah temuannya, bukan kekurangan panduan ini.
Di luar toll-free, Bandwidth tidak mengelola daftar opt-in atau opt-out untuk Anda. Panduan mereka sendiri menyatakannya dengan jelas: tanggung jawab untuk mematuhi perintah dan memelihara daftar ada di tangan pelanggan. Toll-free adalah pengecualian, di mana STOP dan variannya diterapkan di lapisan jaringan terlepas dari konfigurasi Anda; long code dan short code tidak mendapat penanganan seperti itu.
Jadi pada migrasi ini, daftar otoritatif sudah ada di tangan Anda. Bisa berupa tabel, flag pada catatan kontak, atau pengecekan yang dijalankan jalur pengiriman Anda sebelum memanggil API, dan tugas pertama adalah menentukan mana yang otoritatif, bukan meminta ekspor dari siapa pun. Log pesan masuk Anda sendiri adalah cadangan: beberapa opt-out berasal dari pesan masuk, sementara yang lain datang melalui dukungan, formulir, atau channel preferensi lain.
Kemudian impor melalui suppression loop. Satu suppression Bird adalah satu pasangan pengirim-dan-pelanggan, jadi pelanggan yang Anda hentikan di tiga pengirim menjadi tiga record. Membaca dan mengelola suppression berisi perintahnya, dan alasan mengapa suppression manual memblokir setiap kategori termasuk transaksional.
Tentukan siapa pemilik daftar setelah cutover, karena di sinilah Anda mendapat sesuatu dan bisa kehilangan jejak atasnya. Bird menjawab kata kunci stop dari katalognya sendiri per negara, jadi begitu Anda mengirim di sini, platform mengelola suppression untuk Anda: pelanggan yang mengirim pesan STOP menghasilkan record dengan reason keyword_stop tanpa aplikasi Anda melakukan apa pun. Jika kode Anda tetap menyimpan daftarnya sendiri dan tetap menerapkannya, keduanya akan menyimpang, dan gejala yang umum adalah pelanggan yang melanjutkan di satu sisi tapi tidak di sisi lain. Jaga agar pemilik preferensi audiens tetap eksplisit dan sinkronkan perubahan yang relevan secara sengaja. Suppression pengirim saja tidak mencakup preferensi seluruh workspace atau permintaan di luar katalog kata kunci. Reason menumpuk, bukan menggabung, jadi pasangan yang Anda impor sebagai manual yang kemudian mengirim pesan STOP memiliki dua record, dan pesan tetap dihentikan sampai keduanya berakhir.
Terjemahkan status pengiriman
Gunakan tabel ini untuk membandingkan konsep siklus hidup, bukan untuk mengganti nama event secara mekanis. Bird memilih event kegagalan dari status dan reason yang dilaporkan. Permintaan API yang ditolak tidak membuat pesan; penolakan setelah diterima dapat menghasilkan sms.rejected, termasuk penolakan carrier. Bukti pengiriman yang tidak ada tetap berstatus unknown. Simpan status dan kode mentah dari provider bersama hasil yang sudah Anda normalisasi.
| Hasil | Tipe callback Bandwidth | Bird |
|---|---|---|
| API menerima pesan | respons 202, tanpa event | sms.accepted |
| Diserahkan ke carrier | message-sent | sms.sent |
| Carrier mengonfirmasi pengiriman | message-delivered | sms.delivered |
| Tidak pernah sampai ke carrier | message-failed | sms.rejected |
| Carrier menolak | message-failed | sms.failed |
| Carrier melaporkan tidak terkirim | message-failed | sms.undelivered |
| Carrier menyerah | message-failed | sms.expired |
| Permintaan ditolak saat admisi | error permintaan | error HTTP; tidak ada pesan atau event |
Dua hal dari tabel itu perlu Anda tindaklanjuti, bukan lewatkan begitu saja.
Bangun ulang penanganan status terminal berdasarkan record pesan dan timestamp event Bird. Pengiriman webhook dapat berulang atau datang tidak berurutan; consumer Anda tidak boleh mengasumsikan satu pengiriman dari satu callback akhir. Status ditolak dan status gagal kirim dapat memilih event Bird yang berbeda meskipun keduanya berasal dari downstream.
message-sending tidak ada barisnya karena hanya untuk MMS, dan message-read hanya untuk RBM; keduanya tidak aktif untuk SMS.
Dua mekanisme berubah bersama namanya:
- Subscription menggantikan Application. Bandwidth merutekan callback berdasarkan applicationId yang disebutkan pesan. Bird mengirim ke endpoint yang didaftarkan workspace Anda, masing-masing di-subscribe ke tipe event yang diinginkan, jadi consumer baru adalah subscription baru, bukan Application baru dan deploy ulang.
- Standard Webhooks menggantikan autentikasi callback mereka. Bird mengirim JSON yang ditandatangani sesuai Standard Webhooks; ganti verifikasinya dengan resep di Webhooks & events.
Daftarkan endpoint sekali, sebutkan tipe event yang diinginkan handler Anda: event sms.* di atas adalah daftar yang perlu di-subscribe, dan tidak ada wildcard yang menggantikannya. Buat endpoint berisi perintahnya dan satu hal yang harus benar pada panggilan pertama, yaitu menyimpan signing secret yang ditampilkan respons tepat satu kali.
Cutover
Destinasi, pengirim, dan ramp trafik tidak bergantung pada provider dan dibahas di panduan utama. Dua item khusus Bandwidth perlu masuk rencana cutover: brand dan campaign 10DLC Anda terdaftar di The Campaign Registry melalui Bandwidth dan tidak otomatis menjadi registrasi Bird. Konfirmasikan prosedur migrasi atau registrasi yang berlaku sebelum mengirimkan pekerjaan berbayar. Nomor yang Anda miliki di Bandwidth memerlukan porting yang diatur oleh tim dukungan, sesuai jadwal mereka, bukan jadwal Anda.
Untuk persyaratan sisi Bird, mulai dari Registrasi 10DLC: halaman itu membahas arti setiap field, tipe entitas yang dikenali registry, dan panggilan requirements yang memberi tahu Anda apa yang perlu disiapkan sebelum membuat brand, yang merupakan langkah berbayar.
Langkah selanjutnya
-
Bandingkan Bird dan Bandwidth untuk SMS: evaluasi produk dan pertimbangan migrasi
-
Mengirim SMS: payload tujuan porting Anda, secara lengkap
-
Opt-out dan kata kunci: cakupan kata kunci per negara dan pengelolaan suppression
-
Event SMS: kosakata event yang menjadi tujuan handler callback Anda
-
Webhooks & events: pengaturan endpoint dan verifikasi Standard Webhooks
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.