WhatsApp API Chakra Chat: Panduan Lengkap untuk Developer tentang Otomatisasi WhatsApp

TL;DR: Chakra Chat API berjalan di atas WhatsApp Cloud API dan menambahkan hal-hal yang tidak tersedia secara langsung melalui akses Meta mentah: kunci API dengan cakupan peran, format webhook yang lebih mudah digunakan selain penerusan penuh dari Meta, pengelolaan prospek dan kampanye bawaan, endpoint panggilan, serta lapisan Platform/CRM yang lebih luas (proses, tugas, pengguna) untuk membangun alur kerja nyata — bukan sekadar mengirim pesan. Panduan ini membahas autentikasi (kunci API, peran, token Bearer), enam area kapabilitas yang menjadi dasar pengorganisasian API, batas laju (200 panggilan/menit), cara kerja webhook masuk dan validasi HMAC, kapan sebaiknya menggunakan SDK TS/JS resmi dibandingkan panggilan HTTP langsung, serta pola integrasi — sinkronisasi CRM, pemicu otomatisasi melalui alat seperti n8n, platform e-commerce seperti Shopify, dan pengiriman siaran — yang mencakup sebagian besar kasus penggunaan di dunia nyata. Baca panduan ini sebelum membuka dokumen API tingkat endpoint — panduan ini menjelaskan alasan di balik sistem dan gambaran strukturnya, bukan hanya setiap panggilan satu per satu.

Pendahuluan

Jika Anda sedang mengevaluasi Chakra Chat API, kemungkinan besar Anda sudah melihat langsung dokumen WhatsApp Cloud API dan bertanya-tanya apa yang sebenarnya ditambahkan oleh lapisan BSP. Panduan ini menjawabnya, lalu membahas mekanisme praktis — autentikasi, arsitektur, batas laju, webhook, SDK, dan pola integrasi yang paling sering dibangun oleh developer. Untuk detail tingkat endpoint (skema permintaan/respons, parameter), dokumen Chakra API adalah referensi yang sebaiknya tetap Anda buka saat membaca panduan ini.

Kapabilitas Chakra API dibandingkan WhatsApp Cloud API secara langsung

Cloud API Meta adalah lapisan dasar — API inilah yang benar-benar mengirim dan menerima pesan WhatsApp, mengelola templat, serta menangani infrastruktur nomor telepon. Setiap Penyedia Solusi WhatsApp Business, termasuk Chakra, pada akhirnya dibangun di atasnya. Jadi, mengapa tidak berintegrasi langsung dengan Meta?

Bagi beberapa tim, pilihan itu cukup masuk akal. Namun, integrasi langsung berarti Anda harus menangani semua hal yang tidak disediakan Meta secara bawaan: verifikasi bisnis dan alur onboarding, alat untuk persetujuan templat, kotak masuk yang mudah digunakan oleh anggota tim nondeveloper, dan — yang sangat penting untuk hal-hal di luar satu alur otomatis — logika bisnis pendukung seperti pelacakan prospek, pengelolaan kampanye, dan pencatatan ala CRM yang tidak dikenal oleh API Meta.

Hal-hal yang ditambahkan Chakra API di atas akses Cloud API mentah:

• Penerusan langsung dan format webhook yang lebih mudah digunakan. Anda dapat menerima peristiwa dalam format mentah Meta secara langsung, atau format peristiwa Chakra yang dinormalisasi dan lebih mudah digunakan — pilih sesuai kebutuhan setiap kasus penggunaan.
• Kunci API dengan cakupan peran sebagai pengganti satu kredensial untuk seluruh akun, sehingga setiap integrasi (sinkronisasi Shopify, otomatisasi n8n, dasbor internal) hanya memiliki akses yang benar-benar dibutuhkan.
• Lapisan Prospek dan Kampanye — endpoint khusus untuk membuat dan memperbarui prospek serta mengelola kampanye prospek, sehingga Anda tidak perlu membangun model data tersebut sendiri di atas peristiwa pesan mentah.
• Lapisan Platform/CRM — Proses, Tugas, Pengguna, dan Pekerjaan Latar Belakang yang menyediakan komponen umum untuk alur kerja dan pencatatan, berdampingan dengan endpoint khusus WhatsApp. Fitur ini berguna ketika integrasi WhatsApp merupakan salah satu bagian dari sistem operasional yang lebih luas.
• Endpoint API panggilan untuk kemampuan panggilan suara WhatsApp — pengaturan, izin, dan pengelolaan panggilan — sebagai area kapabilitas yang didukung secara bawaan, bukan sesuatu yang ditambahkan secara terpisah.
• Kotak masuk bersama dan perangkat untuk pengguna nondeveloper di dalam akun yang sama, sehingga API bukan satu-satunya cara untuk mengakses sistem — tim dukungan dan pemasaran bekerja di platform yang sama dengan yang digunakan untuk membangun integrasi Anda.

Kapan integrasi Meta langsung mungkin tetap menjadi pilihan yang tepat: jika Anda membangun infrastruktur berskala sangat besar dengan tim platform khusus, atau membutuhkan fungsionalitas Cloud API sesaat setelah Meta merilisnya, sebelum lapisan BSP mana pun sempat menyusul. Bagi sebagian besar tim produk dan pertumbuhan — siapa pun yang membangun otomatisasi, sinkronisasi CRM, atau alur yang berhadapan langsung dengan pelanggan tanpa ingin mengelola seluruh tumpukan infrastruktur pesan — API BSP seperti milik Chakra menawarkan jalur yang lebih cepat dan lebih mudah dipelihara.

Autentikasi: Kunci API, Peran, dan Token Bearer

Setiap panggilan Chakra API diautentikasi menggunakan kunci API, dan pengaturannya sengaja dirancang berdasarkan prinsip hak akses minimum, bukan satu kredensial dengan akses penuh.

Membuat kunci API:

1. Buka bagian API Keys di akun Chakra Chat Anda.
2. Beri nama yang jelas — karena kemungkinan besar Anda akan memiliki beberapa kunci seiring waktu, penamaan berdasarkan kasus penggunaan ("n8n-support-bot," "shopify-order-sync") akan jauh memudahkan pengelolaan nantinya dibandingkan nama umum.
3. Tambahkan deskripsi opsional sebagai konteks tambahan.
4. Tetapkan Access Role. Kunci tersebut hanya mewarisi hak akses dari peran yang Anda tetapkan — tidak lebih.

Menggunakan kunci: setelah dibuat, buka tampilan detail kunci dan temukan bagian Access Tokens . Token di sana harus Anda sertakan sebagai token Bearer di header Authorization pada setiap permintaan API:

Authorization: Bearer {your_access_token}

Panduan utama yang paling penting dalam praktik: selalu batasi cakupan kunci pada hak akses minimum yang benar-benar dibutuhkan oleh kasus penggunaan. Berikut beberapa kebiasaan konkret yang bisa diterapkan:

• Gunakan kunci terpisah untuk setiap integrasi, bukan satu kunci bersama untuk semua otomatisasi. Jika sebuah integrasi tertentu disusupi atau bermasalah, kunci dengan cakupan terbatas akan membatasi dampaknya pada hak akses integrasi tersebut.
• Berhati-hatilah dengan kunci yang terekspos di frontend. Kunci API apa pun yang digunakan dalam kode sisi klien dapat dilihat oleh siapa saja yang memeriksa lalu lintas jaringan — kunci ini harus memiliki hak akses seminimal mungkin, dan idealnya tidak boleh memiliki akses tulis ke operasi sensitif seperti pengiriman pesan atau data prospek.
• Tinjau peran kunci secara berkala, terutama seiring perkembangan integrasi — kunci yang dibuat untuk kasus penggunaan awal yang terbatas terkadang mendapat tanggung jawab lebih luas seiring waktu tanpa peninjauan ulang perannya.

Arsitektur API: Enam Area Kapabilitas

Chakra API disusun berdasarkan enam area kapabilitas praktis. Memahami strukturnya sejak awal akan mempercepat pencarian endpoint yang tepat nantinya, tanpa harus menelusuri seluruh referensi setiap kali.

1. Pesan — mengirim dan menerima pesan WhatsApp secara langsung. Cakupannya meliputi pesan sesi (bebas, dalam jendela 24 jam), unggah dan pengambilan media, pengelolaan kunci WhatsApp Flows, serta pengelolaan Grup (membuat, melihat daftar, mengelola peserta dan permintaan bergabung). Di sini tersedia jalur penerusan dalam format Meta dan endpoint pesan khusus Chakra.

2. Templat — membuat, melihat daftar, dan memperbarui templat pesan WhatsApp, serta endpoint khusus untuk mengirim pesan templat ke nomor telepon tertentu atau dalam konteks Proses (lihat bagian Platform di bawah). Pengiriman templat dan pengelolaan templat sengaja dipisahkan menjadi kelompok endpoint yang berbeda, karena siklus pembuatan/pengelolaan (yang tunduk pada proses persetujuan Meta) berbeda dari tindakan mengirim templat yang sudah disetujui.

3. Prospek — membuat dan memperbarui catatan prospek berdasarkan nomor telepon, sehingga Anda memiliki cara terstruktur untuk melacak calon pelanggan dan pelanggan yang terhubung dengan percakapan WhatsApp, tanpa harus membangun model data tersebut dari awal di atas data chat mentah.

4. Kampanye — menambahkan atau menghapus nomor telepon dari kampanye prospek, sebagai komponen dasar untuk rangkaian pesan keluar yang terstruktur (alur pemeliharaan prospek, segmen siaran), bukan sekadar pengiriman satu kali.

5. Panggilan — cakupan WhatsApp Calling API: mengambil dan mengatur setelan panggilan untuk nomor telepon, memeriksa status izin panggilan (apakah kontak tertentu telah memberikan izin untuk panggilan yang diprakarsai bisnis), dan mengelola panggilan aktif.

6. Platform/CRM — lapisan alur kerja generik: Proses (membuat, memperbarui, mencantumkan, operasi massal, menghapus — pada dasarnya berupa catatan terstruktur yang dapat dikonfigurasi), Tugas, Pengguna, Foto, dan Pekerjaan Latar Belakang. Bagian API ini sama sekali tidak spesifik untuk WhatsApp — ini adalah serangkaian komponen dasar CRM/alur kerja yang ringan, tersedia bersama kemampuan pengiriman pesan. Fitur ini berguna jika Anda ingin integrasi WhatsApp dan data operasional yang lebih luas berada dalam sistem yang sama, alih-alih dirangkai dari berbagai alat terpisah.

Selain enam bagian ini, ada dua area pendukung yang perlu Anda ketahui: Chat & Pesan Chat (mencantumkan chat dan riwayat pesan untuk nomor telepon atau percakapan — berguna untuk membuat tampilan kotak masuk kustom atau mengambil konteks ke sistem lain) dan Akses Partner (pembuatan Connect Token dan pengelolaan konfigurasi plugin WhatsApp/WABA — relevan jika Anda membangun di atas Chakra sebagai partner yang menyematkan layanan, bukan integrasi untuk satu akun saja).

Batas Laju dan Artinya dalam Praktik

Chakra menerapkan batas 200 panggilan API per menit. Angka inilah yang perlu menjadi acuan desain, bukan sekadar diketahui.

Artinya dalam praktik:

• Operasi massal perlu dilakukan secara bertahap, bukan dengan memaksakan semua permintaan. Jika Anda menyinkronkan daftar prospek yang besar atau mengirim siaran ke ribuan penerima, susun pekerjaan dalam beberapa kelompok dan atur jeda pengiriman, alih-alih mengirim setiap permintaan secepat mungkin dalam loop kode Anda.
• Terapkan penanganan jeda bertahap. Integrasi apa pun yang melakukan panggilan secara sering harus menangani respons batas laju dengan baik — coba lagi dengan jeda bertahap, alih-alih menggagalkan seluruh operasi atau langsung membanjiri API setelah menerima respons batas.
• Arsitektur berbasis webhook secara alami akan tetap berada di bawah batas untuk sebagian besar kasus penggunaan, karena Anda merespons peristiwa masuk alih-alih melakukan polling. Ini menjadi alasan tambahan untuk mengandalkan webhook (dibahas berikutnya) daripada pola polling untuk aktivitas yang banyak membaca data, seperti memeriksa pesan baru atau pembaruan status.
• Pekerjaan siaran atau sinkronisasi bervolume tinggi sebaiknya dijalankan sebagai pekerjaan latar belakang, bukan disertakan dalam permintaan yang ditujukan kepada pengguna — endpoint Background Job di lapisan Platform tersedia antara lain untuk tujuan ini, sehingga Anda dapat melacak operasi batch yang berjalan lama tanpa terhambat batas 200 per menit secara langsung.

Webhook: Peristiwa Masuk dan Fungsinya

WhatsApp — dan dengan demikian API Chakra — beroperasi secara asinkron. Saat Anda mengirim pesan, API menerima permintaan tersebut, lalu menerbitkan peristiwa yang menunjukkan apakah pesan terkirim, diterima, dibaca, atau gagal. Pesan masuk dari pelanggan juga dikirim sebagai peristiwa, bukan sesuatu yang perlu Anda pantau dengan polling. Karena itu, webhook menjadi fondasi bagi setiap integrasi real-time.

Ada dua jenis webhook yang berbeda, dan memilih yang tepat itu penting:

Webhook peristiwa pass-through — mengirimkan format peristiwa mentah Meta langsung ke endpoint Anda, tanpa perubahan. Peristiwa ini mencakup pesan masuk, peristiwa status, notifikasi pembaruan template, dan pembaruan tingkat akun. Konfigurasikan melalui tab "More" di halaman WhatsApp Setup, pada kolom URL webhook pass-through. Karena formatnya sama persis dengan dokumentasi Meta, opsi ini tepat jika Anda sudah familier dengan payload Cloud API atau memerlukan akses ke jenis peristiwa yang tidak tercakup dalam format yang dinormalisasi.

Webhook peristiwa Chakra — menggunakan format yang lebih mudah dipahami dan dinormalisasi untuk pilihan jenis peristiwa tertentu. Konfigurasikan melalui halaman WhatsApp Setup yang sama dengan mengaktifkan "Chakra Webhooks" dan memilih jenis peristiwa yang ingin diterima. Peristiwa dikirim dengan dua kunci yang konsisten: event (salah satu dari message, status, message_echo, atau smb_message_echo) dan payload (data pesan atau status pengiriman yang sesuai). Ini pilihan bawaan yang lebih baik untuk sebagian besar integrasi, karena Anda tidak perlu mengurai struktur peristiwa Meta yang bertingkat lengkap untuk kasus sederhana seperti "beri tahu saya saat pelanggan membalas."

Contoh peristiwa pesan teks masuk (format pass-through) memberi gambaran tentang bentuk data yang akan Anda tangani:

{  "object": "whatsapp_business_account",  "entry": [{    "id": "83784929738012",    "changes": [{      "value": {        "messaging_product": "whatsapp",        "metadata": { "display_phone_number": "917259775805", "phone_number_id": "694794789348887" },        "contacts": [{ "profile": { "name": "John" }, "wa_id": "919911223344" }],        "messages": [{          "from": "919911223344",          "id": "wamid.xxxx",          "timestamp": "1756322278",          "text": { "body": "Hi, can you please help me out with an issue" },          "type": "text"        }]      },      "field": "messages"    }]  }]}

Amankan webhook Anda dengan validasi HMAC. Karena endpoint webhook harus dapat diakses secara publik dan tidak memiliki persyaratan autentikasi bawaan, penting untuk memverifikasi bahwa permintaan masuk benar-benar berasal dari Chakra. Mekanismenya:

1. Atur rahasia HMAC di Admin → Team → Secrets pada akun Chakra Anda. Setelah diatur, setiap peristiwa webhook akan menyertakan header X-Chakra-Signature-256 .
2. Di sisi Anda, hitung hash HMAC-SHA256 dari string isi permintaan mentah (bukan objek JSON yang sudah diurai atau diserialisasi ulang — banyak framework HTTP mengubah isi permintaan, sehingga perbandingan tidak akan cocok) dengan rahasia Anda sebagai kunci.
3. Bandingkan hash yang Anda hitung dengan nilai di X-Chakra-Signature-256 (catatan: nilai header tidak memiliki awalan sha256= , berbeda dengan konvensi beberapa penyedia lain). Jika cocok, payload tersebut terautentikasi dan tidak diubah.

💡Jika langkah ini dilewati, siapa pun yang mengetahui URL webhook Anda dapat mengirim peristiwa palsu ke sana — langkah ini sebaiknya dianggap wajib untuk setiap integrasi produksi, bukan sekadar penguatan keamanan opsional.

SDK — Kapan Menggunakannya dan Kapan Memilih Panggilan API Mentah

Chakra menyediakan SDK TypeScript/JavaScript resmi, @chakrahq/chakra-chat-sdk, yang dapat digunakan di lingkungan JavaScript sisi server maupun sisi klien.

npm i @chakrahq/chakra-chat-sdk

Semua permintaan melalui SDK menggunakan autentikasi dengan token akses Bearer yang sama seperti untuk panggilan API mentah. Token cukup diberikan sekali saat inisialisasi, bukan ditambahkan secara manual pada setiap panggilan.

SDK lebih tepat digunakan jika:

• Anda mengembangkan di lingkungan Node.js atau JavaScript/TypeScript dan menginginkan bentuk permintaan/respons bertipe, alih-alih menyusun sendiri panggilan HTTP dan mengurai JSON mentah.
• Anda memanggil beberapa endpoint dalam layanan yang sama dan menginginkan satu klien yang diinisialisasi, alih-alih mengulang logika header autentikasi di setiap bagian.
• Anda ingin mempercepat pengembangan awal dan tidak keberatan mengikuti jadwal rilis SDK untuk endpoint yang lebih baru.

Panggilan HTTP mentah lebih tepat jika:

• Anda melakukan integrasi dari lingkungan non-JS (Python, Ruby, Go, atau alat low-code seperti node HTTP Request di n8n) — API dapat digunakan sepenuhnya melalui permintaan HTTP biasa. Pola ini justru lebih umum untuk integrasi dengan platform otomatisasi, karena alat seperti n8n menggunakan node HTTP secara langsung, bukan mengimpor paket npm.
• Anda memerlukan endpoint yang tersedia di API mentah, tetapi belum tercakup dalam versi SDK saat ini.
• Anda membuat integrasi sederhana untuk satu kebutuhan khusus, sehingga menambahkan dependensi SDK lengkap tidak sepadan hanya untuk beberapa panggilan.

Dalam praktiknya, sebagian besar tim akhirnya menggunakan keduanya: SDK untuk layanan backend inti yang rutin berkomunikasi dengan Chakra, dan panggilan HTTP mentah untuk integrasi yang lebih sederhana seperti alur kerja platform otomatisasi atau fungsi serverless yang dipicu oleh webhook.

Pola Integrasi Umum

Sinkronisasi CRM. Gunakan endpoint Leads (Create a lead, Update Lead By Phone Number) untuk menyinkronkan catatan pelanggan atau prospek seiring berjalannya percakapan WhatsApp. Padukan dengan endpoint Process/Task di lapisan Platform jika Anda ingin catatan terstruktur dan status alur kerja dilacak dalam sistem yang sama, alih-alih bolak-balik memperbarui CRM eksternal setiap kali ada perubahan.

Picu otomatisasi melalui n8n. Pola yang umum: konfigurasi webhook pass-through agar mengarah ke node pemicu webhook n8n, filter peristiwa pesan, teruskan konten pesan ke node AI Agent (atau logika pemrosesan lainnya), lalu kirim respons kembali melalui node HTTP Request yang langsung memanggil endpoint messages:

POST https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v22.0/{whatsappPhoneNumberId}/messagesAuthorization: Bearer {chakraAccessToken}Content-Type: application/json

Nilai pluginId dan whatsappPhoneNumberId tersedia di halaman WhatsApp Setup pada akun Chakra Anda — ID plugin melalui menu tiga titik di sebelah Save, dan Meta ID nomor telepon melalui ikon roda gigi di samping daftar nomor telepon. Pola ini — webhook masuk, pemrosesan, lalu panggilan HTTP keluar — dapat diterapkan jauh melampaui n8n, ke alat otomatisasi alur kerja apa pun yang mendukung pemicu webhook dan node permintaan HTTP.

Otomatisasi siklus hidup pesanan e-commerce (integrasi seperti Shopify). Daripada membuatnya dari webhook mentah, platform seperti Shopify biasanya terhubung melalui lapisan sinkronisasi tanpa kode yang secara otomatis memetakan peristiwa siklus hidup pesanan (dibuat, dipenuhi, dikirim, diterima) ke pengiriman pesan template, sekaligus mengirim peristiwa checkout yang ditinggalkan ke rangkaian template pemulihan keranjang. Untuk platform e-commerce khusus atau non-Shopify tanpa integrasi bawaan, pola yang sama dapat dibuat langsung melalui API: webhook status pesanan dari platform Anda memicu handler sisi server yang memanggil endpoint pengiriman template dengan variabel yang tepat, diisi dari data pesanan.

Kirim siaran melalui API. Untuk mengirim template Marketing atau Utility ke segmen kontak — bukan sebagai balasan percakapan tunggal — polanya adalah: buat daftar penerima (sering kali melalui endpoint Campaigns, dengan menambahkan nomor telepon ke kampanye prospek), lalu lakukan pengiriman berulang ke endpoint pengiriman template, dengan mematuhi batas laju 200 panggilan per menit melalui pengelompokan dan jeda bertahap seperti yang dijelaskan di atas. Untuk daftar besar, menjalankannya sebagai tugas latar belakang alih-alih perulangan sinkron membuat operasi lebih tangguh terhadap kegagalan parsial dan jeda akibat batas laju.

Langkah Selanjutnya

Panduan ini membahas arsitektur dan alasannya — detail di tingkat endpoint (isi permintaan yang tepat, skema respons, dan daftar lengkap operasi yang tersedia di setiap area kemampuan) tersedia di dokumentasi API Chakra. Berikut beberapa dokumentasi yang sebaiknya Anda tandai saat mulai membuat integrasi:

• Kunci API — membuat dan menentukan cakupan kunci
• Webhook Peristiwa Masuk — referensi lengkap webhook dan validasi HMAC
• Batas Laju API
• Chakra Chat SDK
• Cara menemukan pluginId dan whatsappPhoneNumberId — diperlukan untuk sebagian besar integrasi HTTP langsung

Untuk panduan langsung dalam membuat otomatisasi tertentu, panduan integrasi n8n AI Agent dan panduan integrasi Shopify sama-sama menerapkan konsep yang dibahas di sini — mulai dengan panduan ini untuk memahami gambaran sistem, lalu ikuti panduan tersebut untuk membuat integrasi konkret langkah demi langkah.