Platform WhatsApp Business > Cloud API > Panduan

Bermigrasi dari On-Premises API ke Cloud API

Dokumen ini menjelaskan cara memigrasikan nomor telepon bisnis dari On-Premises API ke Cloud API.

Perhatikan bahwa memigrasikan nomor telepon bisnis dari satu API ke API lainnya tidak sama dengan memigrasikan nomor dari satu Akun WhatsApp Business (WABA) ke WABA lainnya.

Untuk bermigrasi dari Cloud API ke On-Premises API, lihat Bermigrasi dari Cloud API ke On-Premises API.

Cara Kerjanya

Proses migrasi melibatkan pembuatan metadata tentang nomor telepon bisnis, kemudian menggunakan data itu untuk mendaftarkan nomor tersebut untuk digunakan dengan Cloud API. Hal ini pada akhirnya membatalkan pendaftaran nomor tersebut dari On-Premises API, karena satu nomor hanya dapat didaftarkan untuk digunakan dengan satu API dalam satu waktu.

Migrasi TIDAK memengaruhi:

nama tampilan, status verifikasi, atau peringkat kualitas nomor telepon bisnis
templat yang digunakan oleh nomor telepon bisnis, atau statusnya
WABA pemilik, status Akun Bisnis Resminya, atau batas pengiriman pesannya

Namun, untuk mendukung migrasi, Anda harus mengetahui perbedaan API dan mengambil tindakan yang sesuai untuk mengatasinya sebelum melakukan langkah-langkah migrasi yang dijelaskan dalam dokumen ini.

Persyaratan

Aplikasi Meta

Anda harus memiliki aplikasi bisnis Meta yang dapat menggunakan Cloud API dan Business Management API dengan data pelanggan yang terdaftar, serta yang dapat mengolah webhooks Cloud API dan Business Management API. Aplikasi juga harus dikaitkan dengan, atau diklaim oleh, Akun Meta Business Anda yang terverifikasi.

Jika Anda tidak memiliki aplikasi Meta Business, atau jika Anda memilikinya tetapi belum mengonfigurasi produk WhatsApp di dalamnya, selesaikan langkah-langkah dalam panduan Memulai Cloud API kami. Setelah menyelesaikan langkah-langkah ini, Anda akan mendapatkan semua aset yang diperlukan untuk menguji API Cloud dan API Pengelola Bisnis.

Tinjauan Aplikasi

Aplikasi Meta Anda harus menjalani Tinjauan Aplikasi dan disetujui (yaitu memiliki akses lanjutan) untuk izin whatsapp_business_messaging dan whatsapp_business_management.

Praktik Terbaik

Setelah memastikan bahwa aplikasi Anda dapat menangani semua perbedaan API, sebaiknya Anda memigrasikan nomor telepon bisnis bervolume rendah terlebih dahulu dan memverifikasi bahwa semua fungsi yang ingin Anda tawarkan dengan Cloud API berfungsi dengan benar. Setelah memverifikasi bahwa semuanya berfungsi dengan baik, migrasikan nomor tambahan.

Kami juga menyarankan Anda melakukan migrasi ketika lalu lintas deployment On-Premises API Anda rendah.

Perbedaan API

Fitur On-Premises API berikut tidak didukung atau diperlakukan berbeda oleh Cloud API. Pastikan aplikasi Anda mampu menangani perbedaan ini sebelum memulai proses migrasi.

Webhooks

Struktur payload webhooks Cloud API dan Business Management API berbeda dari struktur payload API Lokal. Kami menyarankan Anda membuat endpoint webhook baru yang dapat menangani Cloud API dan Business Management API secara eksklusif.

Lihat dokumen berikut untuk membantu Anda memahami perbedaan payload dan cara mengonfigurasi webhooks di aplikasi Anda menggunakan Dasbor Aplikasi:

Konfigurasi: Webhooks untuk WhatsApp
Payload webhook Cloud API: Referensi Payload Notifikasi Webhooks
Payload webhook Business Management API: Pengaturan Webhooks

Perhatikan bahwa setelah Anda memigrasikan nomor telepon bisnis ke Cloud API, Anda harus menggunakan endpoint Akun Bisnis WhatsApp > Aplikasi Langganan untuk mendaftarkan langganan aplikasi Meta Anda ke webhooks di WABA yang terkait dengan nomor bisnis tersebut:

Sintaksis Permintaan

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

Setelah migrasi ke Cloud API selesai, webhooks On-Premises API dari nomor telepon bisnis tidak akan lagi dikirimkan dan pengiriman webhooks Cloud API akan dimulai.

Media

ID Media untuk media apa pun yang diunggah ke On-Premises API tidak dapat digunakan saat mengirimkan pesan dengan Cloud API, jadi Anda harus mengunggah ulang media menggunakan Cloud API untuk membuat ID media baru, atau menggunakan URL media jika media di-hosting di server publik. Lihat Pesan Media dan Template Pesan Berbasis Media.

Perlu diperhatikan bahwa untuk memastikan integritas pesan, beberapa domain hosting media yang diizinkan oleh On-Premises API tidak diizinkan oleh Cloud API. Jika Anda menggunakan layanan hosting untuk media Anda, sebaiknya Anda menguji URL media dalam pesan bentuk bebas dan pesan template sebelum migrasi. Jika Anda yakin host Anda diblokir karena kesalahan, silakan hubungi dukungan.

Kode Kesalahan

Kode kesalahan Cloud API dan Business Management API berbeda dari kode kesalahan On-Premises API. Lihat dokumen berikut:

Validasi Properti

On-Premises API dapat menerima properti yang tidak diketahui dalam payload isi postingan pesan, tetapi Cloud API akan menolak permintaan ini, jadi buat permintaan pengiriman pesan Anda hanya menggunakan properti yang didukung.
On-Premises API mengizinkan penghilangan indeks tombol saat mengirim pesan hanya dengan satu tombol, tetapi Cloud API akan menolak permintaan ini, jadi pastikan permintaan pengiriman pesan Anda yang menyertakan tombol juga menyertakan indeks dan nilainya.
On-Premises API menerima string teks yang berisi spasi di awal atau akhir (atau hanya spasi) pada properti objek tindakan dan tombol saat mengirim pesan interaktif, tetapi Cloud API akan menolak permintaan ini.

Pesan Push-To-Talk

Lokal mengidentifikasi pesan push-to-talk (PTT) di webhooks dengan mengatur messages.type ke voice, tetapi Cloud API mengidentifikasi pesan PTT dengan mengatur messages.audio.voice ke true.

Paket Stiker

Cloud API tidak mendukung paket stiker.

Waktu Henti

Waktu henti dimulai segera setelah Anda melakukan langkah migrasi terakhir (mendaftarkan nomor untuk digunakan dengan Cloud API) dan hanya berlangsung beberapa detik. Selama waktu ini, pesan yang dikirim ke nomor dari pengguna WhatsApp tidak akan diproses tanpa pemberitahuan.

Kami sangat menganjurkan Anda untuk menjadwalkan migrasi pada saat nomor tersebut mempunyai aktivitas rendah, untuk meminimalkan dampak waktu henti.

Throughput

Jika nomor telepon bisnis Lokal memiliki multikoneksi yang menjalankan 2 partisi atau lebih, maka nomor tersebut secara otomatis akan ditingkatkan ke throughput tinggi di Cloud API.

Akun Bisnis Resmi

Jika Anda memigrasikan nomor telepon bisnis yang memiliki status Akun Bisnis Resmi (OBA), statusnya akan dipertahankan jika Anda menyertakan metadata-nya (dihasilkan pada langkah 2) saat mendaftarkan nomor (langkah 3). Jika Anda menghilangkan data ini, angka tersebut akan kehilangan status OBA-nya.

Dukungan Migrasi

Jika Anda memiliki pertanyaan atau memerlukan bantuan terkait migrasi, kirimkan tiket Dukungan Langsung dengan:

Topik: WABiz: Cloud API
Jenis Permintaan: Masalah Migrasi API Lokal -> Cloud API

Langkah 1: Nonaktifkan Verifikasi Dua Langkah

Jika Anda mengetahui PIN nomor telepon bisnis, Anda dapat melewati langkah ini.

Anda memerlukan PIN nomor telepon bisnis saat melakukan langkah 3, jadi jika Anda tidak mengetahui PIN tersebut, Anda harus terlebih dahulu menonaktifkan verifikasi dua langkah di nomor telepon bisnis tersebut. Jika Anda tidak memiliki nomor telepon bisnis, mintalah pemiliknya untuk menonaktifkannya untuk Anda.

Langkah 2: Hasilkan Metadata Nomor Telepon

Gunakan Backup dan Restore API untuk menghasilkan metadata nomor telepon bisnis Anda.

Sintaksis Permintaan

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> bisa berupa string apa pun. Nilai ini akan digunakan untuk mengenkode metadata, jadi pantau terus nilai ini karena Anda akan memerlukannya di langkah berikutnya.

Tanggapan

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

API akan mengembalikan string yang dienkode yang ditetapkan ke properti data yang menjelaskan nomor telepon bisnis Anda dan pengaturannya. Catat nilai ini karena Anda akan membutuhkannya pada langkah berikutnya.

<METADATA> — Ini adalah string yang dienkode yang menjelaskan nomor telepon bisnis Anda dan pengaturannya. Catat nilai ini karena Anda akan membutuhkannya pada langkah berikutnya.
<API_STATUS> — Status deployment On-Premises API Anda.
<API_VERSION> —Nomor versi On-Premises API yang Anda jalankan.

Contoh Permintaan

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Contoh Tanggapan

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Langkah 3: Daftarkan Nomor

Gunakan endpoint Nomor Telepon WhatsApp Business > Daftar Cloud API untuk mendaftarkan nomor untuk digunakan dengan Cloud API.

Sertakan nilai metadata nomor telepon bisnis yang dienkode dan kata sandi dari langkah sebelumnya. Meskipun Anda dapat mendaftarkan nomor tanpa data ini, tetapi data profil nomor telepon bisnis tersebut akan hilang jika tidak disertakan, sehingga dapat memengaruhi status Akun WhatsApp Business sebagai Akun Bisnis Resmi.

Sintaksis Permintaan

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Body Postingan

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — PIN lama atau PIN yang ingin Anda atur di nomor telepon bisnis.
<PASSWORD> — Kata sandi yang Anda gunakan untuk membuat metadata nomor telepon bisnis pada langkah sebelumnya.
<METADATA> — String yang dienkode yang menjelaskan nomor telepon bisnis Anda dan pengaturannya, yang dibuat pada langkah sebelumnya.

Tanggapan

{
  "success": <SUCCESS>
}

API akan menanggapi dengan mengatur success ke true jika pendaftaran berhasil, atau false jika terjadi kesalahan.

Contoh Permintaan

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Contoh Tanggapan

{
  "success": true
}

Langkah 4: Periksa Status Kesehatan Pengiriman Pesan (Opsional)

Minta kolom health_status pada nomor telepon bisnis dan verifikasi bahwa nomor tersebut dapat digunakan untuk berkirim pesan dengan Cloud API. Lihat Status Kesehatan Pengiriman Pesan.

Platform WhatsApp Business | Cloud API | API Pengelolaan Bisnis