# Migrasi SMS dari provider lain

Gunakan panduan ini untuk memindahkan SMS produksi dari provider lain ke Bird. Dua hal menghalangi pengiriman pertama di sini yang ditangani secara berbeda oleh provider Anda saat ini, sehingga keduanya dibahas sebelum kode: negara tujuan pengiriman, dan sender yang digunakan untuk mengirim. Setelah itu, portkan send call, migrasikan daftar opt-out, arahkan ulang laporan pengiriman ke webhook, dan uji terhadap destinasi simulasi sebelum mengalihkan traffic sesungguhnya.

Checklist migrasi:

1. [Aktifkan negara tujuan Anda](#1-aktifkan-negara-tujuan-anda)
2. [Siapkan sender](#2-siapkan-sender)
3. [Petakan send call](#3-petakan-send-call) ke `POST /v1/sms/messages`
4. [Migrasikan daftar opt-out Anda](#4-migrasikan-daftar-opt-out-anda)
5. [Alihkan laporan pengiriman ke webhook](#5-alihkan-laporan-pengiriman-ke-webhook)
6. [Uji terhadap destinasi simulasi](#6-uji-terhadap-destinasi-simulasi) sebelum cutover

Langkah 3, 4, dan 5 bergantung pada provider yang Anda tinggalkan. [Panduan provider](#migrasi-dari-provider-tertentu) Anda memuat pemetaan payload field-by-field, penerjemahan status dan event, serta cara mengekspor daftar opt-out Anda.

Mulai dari langkah 1 dan 2. Registrasi sender adalah proses terlama dalam migrasi SMS: peninjauan oleh operator dan registry bisa memakan waktu lebih lama dari perubahan kode. Evaluasi keduanya sebelum menetapkan tanggal cutover.

## 1. Aktifkan negara tujuan Anda

Workspace Anda memiliki allowlist destinasi default-deny yang awalnya hanya mengaktifkan negara asal organisasi Anda. Pengiriman ke negara lain mengembalikan `422 SMSDestinationNotEnabled` sebelum Bird menyelesaikan sender, sehingga integrasi yang sudah Anda portkan dengan benar tetap gagal pada pesan internasional pertama sampai Anda membuka negara tersebut.

Aktifkan setiap negara tujuan pengiriman Anda di [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations). Ambil daftarnya dari log pesan provider Anda saat ini, bukan dari ingatan: negara yang terlewat menjadi celah diam-diam pada hari cutover, dan negara yang Anda aktifkan tetapi tidak pernah digunakan adalah paparan yang tidak perlu. Default deny juga yang membatasi kerusakan akibat SMS pumping, yaitu traffic penipuan ke nomor premium yang ditagihkan kepada Anda.

## 2. Siapkan sender

Pada pengiriman free-text, `from` adalah sender yang dilihat penerima, dan memiliki salah satu dari tiga bentuk: alphanumeric sender ID, nomor telepon dalam format E.164 yang dimiliki workspace Anda, atau short code. Bentuk mana yang berfungsi bergantung pada negara tujuan, dan sender yang tidak valid di sana ditolak dengan `422` yang menyebutkan alasannya. [Sending SMS](/docs/guides/sms/sending-sms#sender) memuat aturan per bentuk.

Cara mendapatkan masing-masing:

- **Alphanumeric sender ID** Anda buat sendiri di [**SMS** > **Senders**](https://bird.com/dashboard/w/sms/senders). Jika negara tujuan mewajibkan sender ID didaftarkan, ajukan registrasi di sana dan tunggu persetujuan sebelum mengarahkan traffic ke sender tersebut.
- **Traffic bisnis AS melalui local long code** memerlukan 10DLC brand dan campaign yang sesuai, disiapkan di [**SMS** > **10DLC**](https://bird.com/dashboard/w/sms/10dlc), sementara nomor toll-free dan short code khusus memiliki program verifikasi atau aplikasi tersendiri. AS sama sekali tidak menerima alphanumeric sender ID, sehingga sender ID Eropa yang berfungsi di tempat lain tidak memiliki padanan di AS.
- **Nomor** diperoleh melalui alur kerja Numbers, dengan ketersediaan dan provisi terkelola bergantung pada tipe dan tujuan. Periksa [SMS numbers](/products/sms/numbers) untuk jalur yang tepat; menambahkan alphanumeric sender tidak memperoleh nomor.
- **Mempertahankan nomor Anda saat ini** bukan layanan mandiri: Bird tidak memiliki alur port-in yang dapat Anda jalankan dari dashboard. Jika pelanggan membalas ke nomor yang Anda miliki saat ini, ajukan port ke dukungan sebelum menjadwalkan tanggal cutover, dan rencanakan agar port dan perubahan kode menjadi dua kejadian terpisah.

[Pengiriman system-template](/docs/guides/sms/templates) menggunakan format request berbeda. Pengiriman ini tetap memerlukan destinasi dan izin penerima yang sesuai. Ia menyediakan body, kategori, dan sender, sehingga `from` tidak diterima bersamaan dan Bird memilih sender yang valid untuk tujuan tersebut.

## 3. Petakan send call

Endpoint single-send adalah [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message). Buat payload JSON dengan `to`, `from`, `text`, dan `category`, dan panggilan yang berhasil mengembalikan `202 Accepted` dengan message ID berprefiks `sms_`. Pengiriman terjadi setelah respons dan sampai ke Anda melalui event webhook dan endpoint baca. Payload lengkap ada di [Sending SMS](/docs/guides/sms/sending-sms); pemetaan field-by-field dari payload Anda saat ini ada di [panduan provider](#migrasi-dari-provider-tertentu) Anda.

Sebelum memportkan kode, perhatikan perbedaan berikut:

- **Satu penerima per request.** Bird tidak memiliki array penerima. Jika provider Anda saat ini menyebarkan satu panggilan ke banyak nomor, itu menjadi satu panggilan per penerima, atau satu [batch](/docs/guides/sms/sending-sms#batch-sending) pesan independen dalam satu request.
- **`category` wajib pada free text**, dan nilainya adalah `transactional`, `marketing`, `authentication`, atau `service`. Kebanyakan provider menyimpulkan tujuan dari campaign atau sender; di sini Anda mendeklarasikannya per pesan, dan jika negara tujuan mewajibkan sender didaftarkan, registrasi tersebut disetujui untuk kategori tertentu dan pengiriman di luar kategori itu ditolak dengan `422 SenderCategoryNotPermitted`. Status `active` pada sender tidak dapat memberi tahu Anda hal ini sebelumnya, karena dilaporkan tanpa mengacu pada kategori mana pun; baca persyaratan per negara sebagai gantinya. Atur dengan benar saat portasi, bukan memilih satu nilai default untuk semua.
- **Body dibatasi dalam segmen, dan Bird tidak memotong.** Body yang lebih panjang ditolak dengan `422`. Karakter non-GSM-7 mengurangi kapasitas segmen lebih dari setengahnya, jadi jika provider Anda saat ini secara diam-diam mentransliterasi tanda kutip lengkung dan tanda hubung, atur [`options.smart_encoding`](/docs/guides/sms/sending-sms#segments-and-encoding) untuk mempertahankan jumlah segmen yang biasa Anda gunakan. Fitur ini nonaktif secara default karena mengubah body yang Anda susun.
- **Gunakan `tags` untuk dimensi filter dan `metadata` untuk konteks.** Tag adalah pasangan `{name, value}` yang dapat Anda filter dan gunakan untuk memotong analitik; metadata adalah JSON arbitrer yang Bird simpan, kembalikan pada pembacaan, dan kirimkan kembali di setiap event webhook. Field referensi klien tunggal di provider lama Anda biasanya dipetakan ke `metadata`.
- **Penjadwalan pengiriman individual dan MMS outbound memerlukan rencana terpisah.** `scheduled_at`, `media_urls`, `validity_period`, dan `personalization` per penerima adalah [field yang dicadangkan](/docs/guides/sms/sending-sms#reserved-fields), ditolak dengan `422 SMSUnsupportedFeature`. Bagian integrasi tersebut tidak ikut berpindah: tahan pengiriman terjadwal di antrean Anda sendiri dan panggil endpoint kirim pada waktu pengajuan yang dimaksud. Untuk kampanye audiens, evaluasi [Broadcasts](/products/sms/marketing/campaigns) secara terpisah; broadcast bukan sekadar penggantian nama field pada endpoint.
- **Gunakan `Idempotency-Key` untuk percobaan ulang terbatas.** Kirim kunci unik per pesan logis dan gunakan kembali untuk percobaan ulang request identik dalam jendela replay tiga jam. Replay mengurangi request duplikat tetapi bukan jaminan pengiriman tepat-satu-kali. Lihat [Idempotency](/docs/guides/idempotency).

## 4. Migrasikan daftar opt-out Anda

Impor opt-out Anda **sebelum** pengiriman produksi pertama. Mengirim pesan kepada seseorang yang sudah meminta berhenti di provider lama adalah pelanggaran kepatuhan yang menggagalkan migrasi, dan baik operator maupun regulator tidak peduli vendor mana yang kehilangan catatan tersebut.

Supresi Bird mencakup **pasangan sender-dan-subscriber**, yang mungkin lebih sempit dari blokir level layanan, profil, atau akun di provider lama Anda. Pertahankan pencabutan persetujuan orang tersebut di setiap sender dan program yang relevan. Tambahkan setiap pasangan dengan [`POST /v1/sms/suppressions`](/docs/api/reference/create-sms-suppression):

```bash
while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv
```

Impor yang sama dapat dijalankan dari CLI sebagai `bird sms suppressions add --destination +15550001234 --originator +15557654321`.

Dua hal yang perlu diketahui tentang impor ini:

- **Kedua sisi diperlukan untuk supresi khusus sender.** Opt-out seluruh workspace termasuk dalam [preference owner](/docs/guides/sms/opt-outs-and-keywords#opting-out-of-every-sender) yang terpisah. Panggilan ini idempoten: `201` mencatat supresi baru, `200` mengembalikan supresi manual yang sudah ada, sehingga menjalankan ulang impor parsial aman dilakukan.
- **Pasangan yang diimpor mendapat `reason: manual`, yang memblokir setiap kategori termasuk transaksional.** Ini lebih ketat daripada supresi yang Bird catat sendiri dari kata kunci stop. Jika subscriber hanya opt-out dari marketing, pertimbangkan dengan sengaja apakah pasangan tersebut perlu diimpor.

Tinjau perilaku kata kunci dan preferensi yang ada sebelum menonaktifkan kode. Bird menjawab kata kunci yang didukung dan mencatat supresi sesuai katalog negaranya. Pertahankan penanganan untuk permintaan yang tidak didukung, preferensi yang lebih luas, dan saluran kontak lain. Kata kunci dan balasan kampanye kustom menggunakan [Keyword rules](https://bird.com/dashboard/w/sms/keyword-rules). Lihat [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords) untuk cakupan dan lingkup.

## 5. Alihkan laporan pengiriman ke webhook

Daftarkan satu endpoint dengan [`POST /v1/webhooks`](/docs/api/reference/create-webhook) dan subscribe ke daftar tipe event secara eksplisit. Ini adalah perubahan struktural yang diwajibkan kebanyakan provider: alih-alih callback URL per pesan atau per nomor, workspace Anda memiliki endpoint, dan setiap endpoint berlangganan event yang diinginkannya.

Nama event Bird mengikuti `resource.action`. Jalur sukses adalah `sms.accepted`, lalu `sms.sent`, lalu `sms.delivered`, dengan `sms.undelivered`, `sms.failed`, `sms.expired`, dan `sms.rejected` mencakup sisanya, dan `sms.received` membawa balasan ke nomor Anda. Penerjemahan dari kosakata status provider Anda saat ini ada di [panduan provider](#migrasi-dari-provider-tertentu) Anda, dan payload per event ada di [SMS events](/docs/guides/sms/events).

Korelasi berpindah dengan bersih. Setiap event membawa `sms_id`, `workspace_id`, `to`, dan `from`, serta mengembalikan `tags` dan `metadata` dari pengiriman, sehingga handler Anda membaca identifier Anda sendiri langsung dari event tanpa perlu mencari pesan tersebut.

Dua mekanisme yang perlu diportkan bersama handler:

- **Pengiriman ditandatangani sesuai [Standard Webhooks](https://www.standardwebhooks.com)**, menggunakan header `webhook-id`, `webhook-timestamp`, dan `webhook-signature` dengan HMAC-SHA256 atas `{id}.{timestamp}.{raw body}`. Provider yang menandatangani dengan skema sendiri perlu verifikasinya diganti; caranya ada di [Webhooks & events](/docs/guides/webhooks#verify-signatures).
- **Pengiriman bersifat at-least-once dan tidak berurutan.** Deduplikasi berdasarkan `webhook-id` dan urutkan berdasarkan `timestamp` pada payload, bukan berdasarkan urutan kedatangan.

Pesan masuk mengikuti model yang sama. Subscribe ke `sms.received` sekali untuk workspace, bukan mengonfigurasi URL inbound per nomor, dan ingat bahwa Bird tetap mengeluarkan `sms.received` untuk balasan yang cocok dengan kata kunci stop, setelah mencatat supresi.

## 6. Uji terhadap destinasi simulasi

Bird mensintesis hasil pengiriman untuk sekumpulan destinasi uji, sehingga Anda dapat menguji jalur pengiriman yang sudah diportkan dan handler webhook terhadap respons API asli dan pengiriman bertanda tangan asli tanpa perangkat. Ini adalah nomor yang sama yang digunakan beberapa provider untuk kredensial uji, dan pesan ke salah satunya tidak pernah sampai ke operator.

| Destinasi      | Yang dilihat integrasi Anda                                 |
| -------------- | ----------------------------------------------------------- |
| `+15005550001` | Ditolak saat pengajuan dengan `invalid_destination`         |
| `+15005550002` | `sms.sent`, lalu `sms.undelivered` dengan `unreachable`     |
| `+15005550003` | `sms.sent`, lalu `sms.failed` dengan `provider_unavailable` |
| `+15005550004` | `sms.sent`, lalu `sms.failed` dengan `blocked_by_carrier`   |
| `+15005550006` | `sms.sent`, lalu `sms.delivered`                            |
| `+15005550009` | `sms.sent`, lalu `sms.failed` dengan `recipient_opted_out`  |

Tiga ketentuan berlaku, dan dua yang pertama sering menjebak pada workspace baru:

- Ini adalah nomor AS, jadi **United States harus diaktifkan** di Destinations, dan `from` harus berupa sender yang valid untuk AS. Alphanumeric sender ID ditolak di sana.
- **Pengiriman simulasi dikenakan biaya** sesuai tarif normal destinasi. Tidak ada yang sampai ke perangkat, tetapi tagihan wallet bersifat nyata, jadi sesuaikan ukuran smoke test Anda.
- Hasilnya ditentukan oleh destinasi saja. Tidak ada kredensial uji terpisah, dan tidak ada mode uji yang perlu dimatikan.

Smoke test yang memadai mengirim ke `+15005550006` dan memastikan handler Anda berjalan dari `sms.accepted` ke `sms.sent` ke `sms.delivered`; mengirim ke `+15005550002` dan `+15005550009` dan memastikan penanganan kegagalan dan opt-out Anda terpicu pada kode `error` yang tepat; dan mengirim satu pesan nyata ke perangkat yang Anda kendalikan untuk mengonfirmasi sender dan body tampil sesuai harapan.

Lalu lakukan cutover berdasarkan persentase traffic, bukan sekaligus. Pindahkan sebagian kecil pengiriman produksi ke Bird, pantau [log SMS](/docs/guides/sms/sms-log) dan [metrik](/docs/guides/sms/tracking-and-metrics) untuk tingkat pengiriman dan kode error dibandingkan dengan yang dilaporkan provider lama Anda untuk rute yang sama, dan naikkan persentasenya selama angkanya stabil. Pertahankan integrasi lama dalam kondisi siap deploy sampai periode penagihan penuh pertama terlihat benar.

## Migrasi dari provider tertentu

- [Twilio](/docs/guides/sms/migrate/twilio): `PascalCase` form-encoded ke JSON, Messaging Services ke sender, `StatusCallback` ke webhook berlangganan
- [Plivo](/docs/guides/sms/migrate/plivo): `src` dan `dst` ke `from` dan `to`, Powerpacks ke sender, pasangan DND ke supresi
- [Telnyx](/docs/guides/sms/migrate/telnyx): pengiriman yang paling mirip dengan Bird, messaging profiles dipecah menjadi sender dan subscription, opt-out seluruh profil ke pasangan
- [Bandwidth](/docs/guides/sms/migrate/bandwidth): dua host menjadi satu, callback `applicationId` ke webhook workspace, dan daftar opt-out yang sudah dipegang aplikasi Anda sendiri
- [Sinch](/docs/guides/sms/migrate/sinch): batch ke pengiriman tunggal, `body` ke `text`, keanggotaan grup dibangun ulang sebagai supresi
- [Infobip](/docs/guides/sms/migrate/infobip): payload tiga level diratakan, base URL per akun ke host regional, Blocklist diperluas menjadi pasangan
- [Bird Connectivity Platform](/docs/guides/sms/migrate/connectivity-platform): `rest.messagebird.com` API, `originator` dan `recipients` ke `from` dan `to`, callback GET `reportUrl` ke webhook bertanda tangan

## Langkah selanjutnya

- [Bandingkan provider SMS](/products/sms/compare): evaluasi alur kerja produk dan pertimbangan migrasi

- [Sending SMS](/docs/guides/sms/sending-sms): payload pengiriman lengkap, sender, segmen, dan model async 202
- [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords): apa yang Bird jawab untuk Anda, dan cara mengelola supresi
- [SMS events](/docs/guides/sms/events): kosakata event dan payload per event
- [Webhooks & events](/docs/guides/webhooks): pengaturan endpoint, verifikasi tanda tangan, percobaan ulang, dan replay

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)
- [Compare SMS providers](/sms-api/compare) (product)