Menghubungkan perangkat lunak Anda ke WhatsApp

Manajemen API adalah cara sistem lain — perangkat lunak penagihan, toko online, atau backend Anda sendiri — mengirim pesan WhatsApp melalui WizMessage. Di sini Anda menerbitkan kunci API untuk sistem tersebut, menentukan templat WhatsApp yang telah disetujui mana yang boleh dikirimnya, dan mengarahkannya ke webhook agar balasan bisa kembali masuk. Panduan ini menelusuri seluruh alurnya, lalu mendokumentasikan REST API yang akan dipanggil oleh developer Anda.

Dasbor

Di mana kunci API Anda tersimpan

Setiap kunci yang telah Anda terbitkan muncul di sini pada bagian API Keys. Setiap baris menampilkan status kunci, prefiks publiknya (satu-satunya bagian dari kunci yang masih ditampilkan lagi setelah Anda membuatnya), dan berapa banyak panggilan yang telah dilakukannya hari ini. "Manage" membuka kunci tersebut; tombol alih menjedanya tanpa menghapusnya.

1. ▶ Di mana kunci API Anda tersimpan
2. ▶ Kunci yang belum selesai disiapkan

Kunci yang belum selesai disiapkan

Kunci yang belum memiliki templat terpetakan akan menampilkan lencana "Needs setup". Kunci tersebut dapat melakukan autentikasi, tetapi tidak dapat mengirim pesan templat sampai Anda memetakan salah satunya — sehingga integrasi yang baru setengah dikonfigurasi langsung terlihat sekilas, alih-alih baru gagal nanti saat pengiriman.

Penyiapan terpandu

Langkah 1 — Apa yang ingin Anda hubungkan?

"Connect your software" membuka wizard empat langkah. Mulailah dengan menamai kunci sesuai sistem yang akan menggunakannya, lalu pilih preset yang cocok. Preset hanya menyarankan nama field yang masuk akal — preset penagihan menyarankan invoice_number, amount, due_date, customer_name — preset tidak membatasi apa yang boleh Anda petakan.

1. ▶ Langkah 1 — Apa yang ingin Anda hubungkan?
2. ▶ Langkah 2 — Pilih pesannya
3. ▶ Langkah 3 — Ke mana balasan harus dikirim?
4. ▶ Langkah 4 — Mulai digunakan

Langkah 2 — Pilih pesannya

Pilih salah satu templat WhatsApp Anda yang telah disetujui. Templat tersimpan di Meta, bukan di sini — daftar ini diambil secara langsung dari akun WhatsApp Anda yang terhubung, dan hanya templat berstatus APPROVED yang dapat dikirim. Langkah ini opsional: lewati saja jika kunci hanya akan mengirim teks biasa, lalu petakan templat di kemudian hari.

Langkah 3 — Ke mana balasan harus dikirim?

Ketika seseorang membalas pesan Anda, atau laporan pengiriman masuk kembali, kami mengirimkannya melalui POST ke URL yang Anda kendalikan. Biarkan nonaktif jika sistem Anda hanya mengirim. Anda dapat menambahkannya nanti dari tab Webhooks pada kunci tersebut — tidak ada yang bersifat permanen di sini.

Langkah 4 — Mulai digunakan

Menekan Next pada langkah sebelumnya adalah yang sebenarnya membuat kunci — layar ini hanyalah konfirmasinya. Salin ketiga nilainya sekarang: kunci API, rahasia API, dan rahasia penanda tangan webhook hanya ditampilkan tepat satu kali dan tidak dapat dipulihkan setelahnya. Jika Anda kehilangan rahasianya, Anda harus merotasinya, yang berarti memperbarui sistem apa pun yang sedang menggunakannya.

Mengelola kunci

Ikhtisar

Membuka sebuah kunci akan membawa Anda ke tab Overview: apa saja yang boleh dilakukannya, seberapa berat penggunaannya, dan endpoint apa saja yang dapat dipanggilnya. Angka penggunaan dibaca dari log permintaan, sehingga mencerminkan trafik yang sebenarnya.

1. ▶ Ikhtisar

Kunci yang masih perlu disiapkan

Kunci yang belum memiliki templat terpetakan justru terbuka pada tab Setup — wizard yang sama, tersemat langsung di halaman. Perhatikan bahwa tab-nya berbeda dari tangkapan layar sebelumnya: selama sebuah kunci belum memiliki setidaknya satu templat, tab Templates dan Webhooks tidak ditampilkan, karena belum ada apa pun untuk dikerjakan.

1. ▶ Kunci yang masih perlu disiapkan

Templat

Setiap kartu mewakili satu templat yang boleh dikirim oleh kunci ini. Teks isinya adalah pesan sebagaimana disetujui di Meta, dan chip di bawahnya adalah nama variabel yang akan disuplai oleh sistem Anda. "Try it" mengirim pesan uji coba, "Get code" menghasilkan permintaan siap pakai dalam delapan bahasa.

1. ▶ Templat
2. ▶ Membaca variabel — satu hal yang layak dicermati pelan-pelan

Membaca variabel — satu hal yang layak dicermati pelan-pelan

Perhatikan kartu payment_failed_alert. Pesannya berjalan {{1}}, lalu {{3}}, lalu {{2}} — placeholder-nya TIDAK berurutan secara numerik di dalam teks. Chip di bawahnya justru diurutkan secara numerik: customer_name mengisi {{1}}, renewal_date mengisi {{2}}, plan_name mengisi {{3}}. Cocokkan nilai Anda dengan NOMOR-nya, jangan pernah dengan urutan kemunculan placeholder di dalam kalimat. Hal ini paling sering menjebak orang pada templat terjemahan, di mana susunan kata menggeser posisi placeholder.

Tiga tombol pada setiap templat

"Try it" — kirim uji coba tanpa menulis kode

Tombol pesawat kertas membuka templat ini dengan nilai contoh yang sudah terisi, satu untuk setiap nama variabel. Ini cara tercepat memastikan sebuah pemetaan sudah benar sebelum developer Anda menyentuhnya. Perhatikan tombol alihnya: "Simulate Only" adalah bawaannya dan tidak ada apa pun yang keluar — server hanya memantulkan payload Anda kembali. Ubah ke "Send Real Message" dan pesan WhatsApp sungguhan akan terkirim ke nomor di kotak tersebut, serta dikenai biaya.

1. ▶ “Try it” — kirim uji coba tanpa menulis kode
2. ▶ Apa yang dikembalikan oleh pengiriman tersimulasi
3. ▶ “Get code” — permintaan yang sudah dituliskan untuk Anda
4. ▶ Mengganti bahasa
5. ▶ “Edit” — ubah apa yang dikirim sistem Anda
6. ▶ Test API — alat yang sama, endpoint mana pun
7. ▶ Webhook — menerima balasan kembali

Apa yang dikembalikan oleh pengiriman tersimulasi

Menekan Send Request dalam mode Simulate Only mengembalikan permintaan persis seperti yang diterima platform, lengkap dengan status HTTP dan waktu pulang-pergi. Bacalah ini sebagai pemeriksaan bentuk, bukan gladi bersih: ini memastikan JSON Anda terbaca dan kunci Anda diterima, tetapi TIDAK memvalidasi nama variabel Anda terhadap pemetaan dan tidak pernah menghubungi Meta. Payload yang lolos simulasi tetap bisa ditolak saat dikirim sungguhan. Untuk membuktikan pemetaannya sendiri, aktifkan Send Real Message dan kirim ke ponsel Anda sendiri.

"Get code" — permintaan yang sudah dituliskan untuk Anda

Tombol tanda kurung siku menghasilkan permintaan yang siap jalan untuk templat ini dalam delapan bahasa: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go, dan C#. Serahkan kepada siapa pun yang menulis integrasinya. Variabelnya muncul sebagai {{placeholders}} yang dinamai sesuai pemetaan Anda, dan kredensialnya dibiarkan sebagai YOUR_API_KEY / YOUR_API_SECRET — dialog ini tidak pernah mencetak kunci asli Anda, jadi cuplikannya aman ditempelkan ke sebuah tiket.

Mengganti bahasa

Klik bahasa mana pun di bagian atas dan cuplikannya ditulis ulang untuk bahasa itu — panggilan yang sama, header yang sama, klien HTTP milik bahasa tersebut. Setiap cuplikan dibuat saat pertama kali Anda mengekliknya, jadi jeda pemuatan singkat pada pergantian pertama adalah hal wajar. Copy mengambil cuplikan apa adanya: sudah lengkap, termasuk import-nya, dan jika kunci ini mewajibkan tanda tangan, langkah penandatanganannya pun sudah ada di dalamnya.

"Edit" — ubah apa yang dikirim sistem Anda

Ikon pensil membuka pemetaannya sendiri. Maket ponsel di bagian atas adalah pesan sungguhan dengan nama Anda saat ini yang sudah disubstitusikan, sehingga Anda bisa melihat apa yang akan dibaca pelanggan. Di bawahnya, setiap variabel yang terdeteksi dapat diganti namanya, diurutkan ulang, ditandai wajib, atau diberi tipe — tanggal, nilai mata uang, gambar. Mengganti nama variabel juga menggantinya di payload API Anda, sehingga sistem yang masih mengirim nama lama akan mulai gagal: ubah keduanya bersamaan.

Test API — alat yang sama, endpoint mana pun

"Test API" di bagian atas tab adalah "Try it" tanpa terkunci pada satu templat: pilih salah satu dari tiga endpoint pengiriman, ganti templat dari dropdown kedua, dan sunting body-nya sebebas Anda. Gunakan untuk memeriksa panggilan mentah /messages/text atau /messages/template, yang tidak punya kartu sendiri karena tidak terikat pada pemetaan mana pun. Perhatikan bahwa variabel templat ini masih bernama body_1, body_2, body_3 — begitulah rupa templat yang belum dipetakan, dan itulah yang hendak diperbaiki oleh "Edit".

Balasan

Webhook — menerima balasan kembali

Mengirim hanyalah separuh dari sebuah integrasi. Arahkan webhook ke endpoint HTTPS Anda sendiri dan WizMessage akan mengirimkan pesan masuk serta pembaruan pengiriman ke sana melalui POST. Rahasia penanda tangan hanya ditampilkan sekali saat dibuat; verifikasi pada setiap pengiriman agar Anda yakin panggilan tersebut benar-benar berasal dari kami.

Referensi REST API

Semua yang dijelaskan di atas mengonfigurasi kunci. Bagian ini adalah yang benar-benar dipanggil oleh developer Anda. Base URL-nya adalah /api/v1/external. Setiap endpoint memerlukan header autentikasi di bawah ini dan tunduk pada batas kecepatan milik kunci tersebut.

Autentikasi

Kirim kunci API Anda pada setiap permintaan. Jika kunci mengaktifkan "Require signature", Anda juga harus menandatangani permintaan tersebut — dan kunci dengan opsi itu aktif akan langsung menolak panggilan apa pun yang tidak ditandatangani.

Catatan: Tanda tangan hanya diwajibkan ketika kunci mengaktifkan require_signature. Jika tidak, kunci API saja sudah cukup untuk mengirim pesan — dan justru itulah sebabnya kunci ini adalah sebuah rahasia, bukan sekadar pengenal. Perlakukan seperti kata sandi: kunci ditampilkan sekali saja, dan siapa pun yang memegangnya dapat mengirim pesan ke pelanggan Anda.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://your-host/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

Endpoint

Mengirim templat yang telah dipetakan

Inilah payload yang berpasangan dengan tab Templates. Anda mengirim variabel berdasarkan NAMA — nama yang ditampilkan sebagai chip pada kartu templat — dan platform yang menyusun components milik Meta untuk Anda. Itulah inti dari pemetaan templat: sistem penagihan Anda tidak perlu tahu apa pun tentang format component milik Meta.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

Catatan: Nama variabel harus sama persis dengan pemetaannya — nama yang tidak dikenali akan diabaikan, dan nama wajib yang hilang akan ditolak dengan 400. reference sepenuhnya milik Anda: nilainya dikembalikan pada webhook sehingga Anda dapat mengaitkan laporan pengiriman dengan record di sistem Anda sendiri.

Batas kecepatan

Setiap kunci memiliki batasnya sendiri, yang terlihat pada tab Overview — secara default 60 permintaan/menit dan 1.000 pesan/hari. Respons menyertakan sisa kuota, jadi kurangi laju permintaan saat kuota menipis alih-alih terus mencoba ulang hingga membentur batas.