Cloud API

Platform WhatsApp Business > Cloud API

Ringkasan

Cloud API, yang dihosting oleh Meta, memungkinkan bisnis menengah dan besar untuk berkomunikasi dengan pelanggan mereka dalam skala besar. Dengan menggunakan API, bisnis dapat membuat sistem yang menghubungkan ribuan pelanggan dengan agen atau bot, sehingga memungkinkan komunikasi terprogram dan manual. Selain itu, bisnis dapat mengintegrasikan API dengan banyak sistem backend, seperti CRM dan platform marketing.

Protokol HTTP

Cloud API dibangun di atas Graph API, sehingga permintaan dinyatakan menggunakan protokol HTTP dan kombinasi dari parameter URL, judul, dan badan permintaan. Misalnya, panggilan yang umum ke Cloud API dari baris perintah berbasis UNIX akan terlihat seperti ini:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Jika Anda belum terbiasa dengan Graph API, bacalah dokumentasi Graph API kami untuk mempelajari dasar-dasarnya. Perbedaan utama antara Graph API dan Cloud API adalah jenis token akses yang akan sering Anda gunakan, izin sumber daya, sintaksis permintaan, dan sintaksis webhooks. Perbedaan ini dijelaskan secara lebih terperinci di bagian yang sesuai dari set dokumentasi Cloud API.

Sumber Informasi

Ini adalah sumber informasi utama yang akan banyak Anda rujuk saat menggunakan API.

Portofolio Bisnis

Untuk menggunakan API, Anda harus memiliki portofolio bisnis. Jika Anda tidak memiliki portofolio, Anda akan diminta untuk membuatnya sebagai bagian dari proses Memulai kami. Portofolio bisnis berperan sebagai wadah untuk Akun WhatsApp Business (WABA) dan nomor telepon bisnis Anda.

Untuk mempelajari selengkapnya tentang portofolio bisnis, lihat artikel pusat bantuan Tentang portofolio bisnis di Meta Business Suite.

Akun WhatsApp Business

Akun WhatsApp Business mewakili bisnis di Platform WhatsApp Business dan terutama terdiri dari metadata tentang bisnis tertentu. Sebagian besar sumber informasi WhatsApp, seperti Nomor Telepon WhatsApp Business dan Template Pesan WhatsApp terkait dengan WABA.

Anda dapat membuat WABA dengan mengikuti langkah-langkah di dokumen Memulai kami. Untuk mempelajari selengkapnya tentang WABA dan batasannya, lihat Akun WhatsApp Business.

Nomor Telepon WhatsApp Business

Nomor Telepon WhatsApp Business (nomer telepon bisnis) mewakili nomor telepon riil, yang setelah terdaftar untuk digunakan dengan Cloud API, dapat digunakan untuk mengirim dan menerima pesan ke dan dari pengguna WhatsApp melalui API.

Nomor telepon bisnis sebagian besar terdiri dari metadata tentang nomor itu sendiri dan bisnis Anda, dan metadata ini dapat muncul di klien WhatsApp ketika pengguna berinteraksi dengan nomor telepon bisnis Anda.

Anda dapat membuat nomor telepon bisnis dengan mengikuti langkah-langkah di dokumen Memulai kami. Perhatikan bahwa ada larangan dan batasan pada nomor telepon bisnis dan penggunaannya, yang dijelaskan secara terperinci dalam dokumen Nomor Telepon Bisnis kami.

Template Pesan WhatsApp

Template Pesan WhatsApp (template) adalah template yang dapat disesuaikan, yang dapat Anda bangun melalui API dengan menggunakan berbagai komponen template. Setelah dibuat, template akan secara otomatis ditinjau, dan jika disetujui, dapat digunakan dalam pesan template.

Ada dua jenis pesan dasar yang dapat Anda kirim melalui API: pesan bentuk bebas dan pesan template. Dari keduanya, pesan template adalah yang paling terbatas karena memerlukan penggunaan Template Pesan WhatsApp yang disetujui. Namun, karena template harus ditinjau dan disetujui sebelum dapat digunakan, pesan template cenderung tidak menerima umpan balik negatif dari penerima, yang dapat membahayakan kemampuan Anda untuk mengirim pesan kepada pelanggan secara keseluruhan.

Untuk mempelajari selengkapnya tentang template, baca dokumen Template kami.

Webhooks

Webhooks hanyalah muatan JSON yang dikirim menggunakan protokol HTTP ke endpoint publik di server Anda. Cloud API sangat bergantung pada webhooks, karena isi pesan apa pun yang dikirim dari pengguna WhatsApp ke nomor telepon bisnis Anda akan dikirim sebagai webhook, dan semua pembaruan status pengiriman pesan keluar dilaporkan melalui webhook.

Perhatikan bahwa kami menawarkan sampel aplikasi webhook yang dapat Anda klon di Glitch dan Anda gunakan untuk pengujian. Aplikasi hanya meletakkan muatan Webhooks secara langsung ke konsol, sehingga Anda dapat melihat kontennya. Ingatlah bahwa pada akhirnya Anda harus membangun endpoint Anda sendiri di server Anda sendiri di beberapa titik yang mengolah webhooks sesuai dengan logika bisnis Anda sendiri.

Lihat Webhooks Meta untuk mempelajari selengkapnya tentang webhooks dan cara mengolahnya, serta dokumen Webhooks untuk Akun WhatsApp Business kami.

Sumber Daya Pengujian

Saat Anda pertama kali menyelesaikan langkah-langkah di dokumen Memulai kami, WABA untuk pengujian dan nomor telepon bisnis untuk pengujian secara otomatis dibuat untuk Anda.

WABA untuk pengujian dan nomor telepon untuk pengujian berguna untuk tujuan pengujian, karena keduanya melewati sebagian besar batas berkirim pesan dan tidak memerlukan metode pembayaran pada file untuk mengirim pesan template.

Anda dapat menghapus portofolio bisnis dan sumber informasi tesnya, jika:

  • Anda adalah admin di portofolio bisnis yang terkait dengan aplikasi
  • tidak ada aplikasi lain yang terkait dengan portofolio bisnis
  • portofolio bisnis tidak terkait dengan WABA lainnya
  • WABA tidak terkait dengan nomor telepon bisnis lainnya.

Untuk menghapus portofolio bisnis Anda dan sumber informasi tesnya:

  1. Buka panel Dasbor Aplikasi > WhatsApp > Konfigurasi.
  2. Temukan bagian Akun Pengujian.
  3. Klik tombol Hapus.

Autentikasi dan Otorisasi

Token Akses

API mendukung tiga jenis token:

  • Token Akses Pengguna Sistem
  • Token Akses Pengguna Sistem Integrasi Bisnis
  • Token Akses Pengguna

Lihat Token Akses kami untuk menentukan jenis token yang harus Anda gunakan. Perhatikan bahwa token harus diteruskan melalui judul permintaan, bukan sebagai parameter string kueri.

Izin

API bergantung pada izin Graph API berikut. Kombinasi izin yang tepat yang dibutuhkan oleh aplikasi Anda tergantung pada endpoint yang akan diakses oleh aplikasi Anda.

  • business_management — diperlukan jika berinteraksi dengan portofolio bisnis.
  • whatsapp_business_management — diperlukan jika berinteraksi dengan WABA dan analisisnya, atau salah satu template atau nomor telepon bisnisnya.
  • whatsapp_business_messaging — diperlukan untuk mengirim dan menerima pesan ke dan dari pengguna WhatsApp.

Izin ini biasanya diberikan saat membuat token akses di Meta Business Suite. Lihat bagian pembuatan token di dokumen Token Akses kami.

Versi

Pembuatan versi menggunakan protokol penetapan versi Graph API. Ini berarti bahwa semua permintaan endpoint dapat menyertakan nomor versi, dan setiap versi akan tersedia selama kurang lebih 2 tahun sebelum dihentikan dan tidak dapat dipanggil lagi.

Throughput

Untuk setiap nomor telepon bisnis yang terdaftar, Cloud API mendukung hingga 80 pesan per detik (mps) secara default, dan hingga 1.000 mps dengan peningkatan otomatis.

Throughput mencakup pesan masuk dan keluar dan semua jenis pesan. Perlu diperhatikan bahwa nomer telepon, terlepas dari throughput-nya, tetap tunduk pada batas laju kasus penggunaan bisnis Akun WhatsApp Business dan batas berkirim pesan template.

Jika Anda mencoba untuk mengirim lebih banyak pesan daripada yang diizinkan oleh level throughput Anda saat ini, API akan menampilkan kode kesalahan 130429 sampai Anda berada dalam level yang diizinkan lagi. Selain itu, level throughput dimaksudkan untuk kampanye pengiriman pesan yang melibatkan nomor telepon pengguna WhatsApp yang berbeda. Jika Anda mencoba untuk mengirim terlalu banyak pesan ke nomor pengguna WhatsApp yang sama, Anda mungkin akan mengalami kesalahan batas laju pasangan.

Throughput yang Lebih Tinggi

Jika Anda memenuhi persyaratan kelayakan, kami akan secara otomatis meningkatkan nomor telepon bisnis Anda ke 1.000 mps tanpa biaya tambahan. Throughput yang lebih tinggi tidak menimbulkan biaya tambahan atau memengaruhi harga.

Proses peningkatan itu sendiri bisa memakan waktu hingga 1 menit. Selama waktu ini, angka tersebut tidak akan dapat digunakan di platform kami. Jika digunakan di permintaan API, API akan menampilkan kode kesalahan 131057. Setelah ditingkatkan, nomor telepon bisnis juga akan otomatis ditingkatkan untuk kenaikan throughput pada masa mendatang tanpa waktu henti.

Persyaratan Kelayakan

Webhooks

Server webhook Anda harus mampu menahan 3x kapasitas traffic pesan keluar dan 1x kapasitas traffic pesan masuk yang diharapkan. Contoh: jika Anda mengirim 1.000 mps dengan tingkat tanggapan yang diharapkan sebesar 30%, server Anda harus mampu memproses hingga 3.000 webhook status pesan ditambah 300 webhook pesan tambahan yang masuk.

Kami mencoba untuk mengirimkan webhook secara bersamaan, jadi sebaiknya Anda mengonfigurasi dan menguji pemuatan server webhook agar bisa menangani permintaan bersamaan dengan standar latensi berikut:

  • Median latensi tidak melebihi 250 milidetik.
  • Latensi yang melebihi 1 detik berjumlah kurang dari 1%.

Kami akan mencoba mengirim ulang webhook yang gagal hingga 7 hari, dengan penundaan eksponensial.

Pesan Media

Untuk sepenuhnya memanfaatkan throughput yang lebih tinggi, sebaiknya Anda mengunggah aset media Anda ke server kami dan menggunakan ID media yang diberikan di pesan media alih-alih meng-hosting aset di server Anda sendiri dan menggunakan URL aset media. Jika Anda lebih suka (atau harus) meng-hosting aset di server milik Anda sendiri, sebaiknya gunakan caching media.

Mendapatkan Level Throughput

Gunakan endpoint Nomor Telepon WhatsApp Business endpoint untuk mendapatkan level throughput nomor telepon saat ini:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migrasi

Jika Anda memigrasi nomor telepon bisnis yang multikoneksinya menjalankan 2 partisi atau lebih dari On-Premises API ke Cloud API, nomor telepon tersebut secara otomatis akan ditingkatkan ke throughput yang lebih tinggi.

Batas Laju

Lihat Batas laju WhatsApp Business Management API.

Selain batas laju ini, kami memiliki batas yang lebih detail pada sumber daya individu seperti pesan template dan nomor telepon bisnis untuk pengujian:

Metrik yang Tersedia

Sebagai pengguna Cloud API, Anda dapat melihat jumlah pesan yang terkirim dan tersampaikan, serta metrik lainnya. Lihat informasinya di Mendapatkan Metrik Akun.

Penskalaan

Dalam infrastruktur Meta, Cloud API akan otomatis melakukan penskalaan dan penyesuaian untuk menangani beban kerja Anda, dalam batas laju Anda (volume berkirim pesan dan jumlah WABA).

Privasi & Keamanan Data

Buka Ringkasan Privasi & Keamanan kami untuk melihat informasinya.

Enkripsi

Dengan Cloud API, setiap pesan WhatsApp terus dilindungi oleh enkripsi protokol Signal yang mengamankan pesan sebelum meninggalkan perangkat. Hal ini berarti pesan dengan WABA tersampaikan secara aman ke destinasi yang dipilih oleh masing-masing bisnis.

Cloud API menggunakan teknik enkripsi standar industri untuk melindungi data saat transit dan saat tersimpan. API menggunakan Graph API untuk mengirim pesan dan Webhooks untuk menerima peristiwa, dan keduanya beroperasi melalui HTTPS standar industri, dilindungi oleh TLS. Lihat laporan resmi Ringkasan Enkripsi kami untuk mendapatkan detail tambahan.

Lihat laporan resmi Ringkasan Enkripsi kami untuk mendapatkan detail tambahan.

Batas Laju Pasangan

Nomor telepon bisnis terbatas untuk mengirim 1 pesan setiap 6 detik ke nomor telepon pengguna WhatsApp yang sama (0,17 pesan/detik). Ini kira-kira setara dengan 10 pesan per menit, atau 600 pesan per jam. Jika Anda melampaui batas ini, API akan mengembalikan kode kesalahan 131056 sampai Anda berada dalam batas Anda lagi.

Jika perlu, Anda dapat mengirim hingga 45 pesan dalam 6 detik sebagai burst. Jika Anda mengirim burst, pada dasarnya Anda meminjam batas laju pasangan Anda, sehingga Anda akan dicegah untuk mengirim pesan berikutnya kepada pengguna yang sama sampai jumlah waktu yang biasanya diperlukan untuk mengirim pesan “non-burst” sebanyak itu kepada pengguna tersebut telah berlalu. Sebagai contoh, dibutuhkan waktu ~2 menit untuk mengirim 20 pesan “non-burst” kepada pengguna, jadi jika Anda mengirim 20 pesan burst, Anda harus menunggu ~2 menit sebelum Anda dapat mengirim pesan lain kepada pengguna.

Untuk menghindari keharusan menghitung waktu tunggu pesan pasca-burst, kami sarankan Anda mencoba lagi 4^X detik kemudian jika permintaan pengiriman pesan gagal setelah mengirim burst, di mana X = 0 dan bertambah 1 setiap kali percobaan gagal, sampai permintaan berhasil.

Fitur

Pengelola WhatsApp

Pengelola WhatsApp adalah aplikasi web kami yang memungkinkan Anda untuk mengelola sumber daya WhatsApp, seperti WABA, nomor telepon bisnis, dan template, secara manual, dan menyediakan cara mudah untuk melihat insight dan peringkat kualitas atau batasan pada sumber daya ini. Sebagian besar fungsi yang ditawarkan oleh Pengelola WhatsApp juga tersedia melalui API, dengan beberapa pengecualian kecil.

Ada beberapa cara untuk mengakses Pengelola WhatsApp. Setiap jalur mengasumsikan bahwa Anda telah menyelesaikan semua langkah di dokumen Memulai kami.

Melalui Meta Business Suite

  1. Masuk ke Meta Business Suite.
  2. Jika Anda memiliki beberapa portofolio bisnis, gunakan menu pilihan di sebelah kiri untuk memilih akun yang memiliki, atau mempunyai akses ke, WABA yang ingin Anda muat di Pengelola WhatsApp.
  3. Di menu sebelah kiri, buka Akun > Akun WhatsApp.
  4. Pilih WABA.
  5. Di tab Rangkuman, klik tombol Pengelola WhatsApp.

Melalui Dasbor Aplikasi

  1. Buka Aplikasi Saya.
  2. Pilih aplikasi yang terkait dengan WABA yang ingin Anda muat di Pengelola WhatsApp.
  3. Di menu sebelah kiri, arahkan ke WhatsApp > Mulai Cepat.
  4. Klik petak Informasi Akun di bagian WhatsApp Business.

Melalui URL

Anda dapat langsung membuka Gambaran Umum Pengelola WhatsApp, yang menampilkan semua WABA yang dimiliki oleh, atau dibagikan dengan, portofolio bisnis tertentu, dengan mengunjungi:

https://business.facebook.com/wa/manage/home/

Secara default, gambaran umum memuat WABA terbaru yang Anda buat atau dapatkan aksesnya, tetapi Anda dapat menggunakan menu pilihan di sebelah kiri untuk memilih portofolio bisnis yang berisi WABA yang coba Anda akses. Namun, hal ini akan mengeluarkan Anda dari gambaran umum, dan Anda harus menggunakan menu di sebelah kiri dan membuka Akun > Akun WhatsApp > (pilih WABA yang diinginkan) > Pengaturan > Pengelola WhatsApp (tombol).

Atau, jika Anda memiliki beberapa portofolio bisnis, Anda dapat menambahkan ID akun ke ujung URL dan menandainya untuk memudahkan akses:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Kami memiliki koleksi Postman Cloud API yang berisi kueri umum di workspace Platform WhatsApp Business kami.