Gambaran Umum

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.

Penetapan 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 mencoba mengirim terlalu banyak pesan ke nomor pengguna WhatsApp yang sama, Anda mungkin akan mengalami kesalahan batas laju pemasangan (kode kesalahan 131056).

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

• Nomor telepon bisnis harus dapat memulai percakapan dengan pelanggan unik dalam jumlah yang tidak terbatas dalam periode 24 jam yang berkelanjutan.
• Nomor telepon bisnis harus didaftarkan untuk digunakan dengan API Cloud. Jika terdaftar untuk digunakan dengan On-Premises API, nomor tersebut harus dimigrasikan ke Cloud API terlebih dahulu.
• Nomor telepon bisnis harus memiliki peringkat kualitasSedang atau lebih tinggi.

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.
• Kurang dari 1% latensi melebihi 1 detik.

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

Setiap WABA memiliki batas laju jumlah panggilan API. Setiap panggilan API yang dilakukan oleh aplikasi Anda ke salah satu nomor telepon bisnis WABA (yaitu node Nomor Telepon WhatsApp Business atau edge-nya, seperti endpoint Pesan) termasuk dalam perhitungan batasnya.

Batas saat ini adalah 11.880.000 panggilan API per jam bergulir untuk WABA tertentu.

Contoh: dalam periode satu jam, aplikasi Anda dapat melakukan 11,88 juta panggilan API pada Nomor Telepon WhatsApp Business yang terkait dengan WABA A dan 11,88 juta panggilan lainnya pada Nomor Telepon WhatsApp Business yang terkait dengan WABA B. Atau, dalam periode satu jam, aplikasi Anda dapat melakukan total panggilan API hingga 11,88 juta pada kombinasi Nomor Telepon WhatsApp Business berbeda yang terkait dengan satu WABA.

Jika Anda mencapai batas Anda, API akan menanggapi dengan kode kesalahan <80007.

Harap diperhatikan bahwa Business Management API memiliki batas laju yang berbeda. 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:

• Batas laju pesan untuk pengujian: Berlaku untuk WABA yang belum terverifikasi.
• Penilaian kualitas dan batas berkirim pesan: Berlaku untuk WABA terverifikasi.
• Batas laju kapasitas: Berlaku untuk semua akun.
• Batas laju telepon bisnis: Berlaku untuk semua akun dan membatasi throughput per nomor telepon bisnis.

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 keluar dari 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 Gambaran Umum Enkripsi kami untuk mendapatkan detail tambahan.

Lihat laporan resmi Gambaran Umum Enkripsi kami untuk detail tambahan.

Alat

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.