Konsep Dasar

Halaman ini ngerangkum hal-hal yang berlaku di semua endpoint. Sekali baca, sisanya bakal kerasa jauh lebih gampang.

Base URL

Semua endpoint ada di bawah:

https://api-zawa.azickri.com

Request dan response pakai JSON. Buat endpoint yang ada body-nya, jangan lupa kirim header Content-Type: application/json.

Sesi: id + session-id

Zawa nggak pakai API key atau token. Sebagai gantinya, tiap nomor WhatsApp punya satu sesi, dan sesi itu dikenali dari dua nilai yang kamu dapet dari Buat Session:

Header	Diisi dengan	Contoh
id	id dari Buat Session	68b3f0a2c1d4e5f6a7b8c9d0
session-id	sessionId dari Buat Session	0b2f7059-8a90-4f6d-8684-b0e1ce6f0310

Semua endpoint, kecuali POST /session, wajib bawa dua header itu:

curl "https://api-zawa.azickri.com/group" \
  -H "id: 68b3f0a2c1d4e5f6a7b8c9d0" \
  -H "session-id: 0b2f7059-8a90-4f6d-8684-b0e1ce6f0310"

Perlakukan kayak password

Siapa pun yang pegang id dan session-id kamu bisa kirim pesan pakai nomor kamu. Simpan di server aja, jangan di frontend atau aplikasi mobile.

Satu sesi = satu nomor WhatsApp. Kalau mau pakai beberapa nomor, bikin beberapa sesi. Inget juga, WhatsApp cuma ngizinin beberapa perangkat tertaut per nomor (saat ini maksimal 4), dan sesi Zawa makan satu slot.

Siklus Hidup Sesi

Sesi itu "hidup": bisa nyambung, putus, nyambung lagi, sampai akhirnya dihapus. Ini yang terjadi di tiap kondisi:

Kondisi	Yang terjadi
Baru dibuat	isConnected: false. Beberapa detik kemudian qrcode terisi.
QR nggak di-scan sekitar 3 menit	Sesi dihapus otomatis. Request berikutnya dapet 404 session not found.
QR udah di-scan	isConnected: true, qrcode kosong, name dan picture terisi.
Koneksi putus sebentar	Zawa nyambung ulang sendiri dengan jeda yang makin lama (0 detik, 2 detik, 4 detik, dst., maksimal 30 detik).
Kamu logout dari HP	Tautannya dihapus dan Zawa langsung nyiapin QR baru. Scan lagi biar nyambung.
Nomor dipakai di tempat lain atau diblokir WhatsApp	Sesi berhenti dan nggak nyambung ulang. Coba Reset Session.
Terputus lebih dari 30 menit	Sesi dihapus otomatis, termasuk semua datanya.
Kamu panggil Hapus Session	Perangkat tertaut di HP ikut keluar, dan semua data sesi dihapus.

Pantau koneksinya

Ambil Session aman dipanggil kapan aja, bahkan waktu sesinya lagi putus. Cek isConnected secara berkala (misalnya tiap beberapa menit) biar kamu tahu kapan harus scan ulang, sebelum 30 menitnya habis.

Format Nomor, Grup, dan Channel

Kirim Pesan dan Kirim Typing butuh tujuan. Isi salah satu kolom ini:

Kolom	Format	Contoh	Dapet dari mana?
phone	Nomor format internasional	6281234567890	Nomor tujuan
group	ID grup	[email protected]	Ambil Group
newsletter	ID channel	120363000000000000@newsletter	Ambil Channel

Biar nggak ribet, Zawa ngerapihin nomor yang kamu kirim:

• Karakter selain angka dibuang, jadi +62 812-3456-7890 tetap jalan.
• Awalan 0 otomatis diganti 62, jadi 081234567890 jadi 6281234567890.
• Setelah dirapihin, nomornya minimal harus 8 digit. Kalau kurang, kamu dapet 400 invalid receiver.

Awalan 0 selalu dianggap nomor Indonesia

Buat nomor luar negeri, selalu pakai kode negara. Contohnya 60123456789 buat Malaysia, bukan 0123456789.

Beberapa hal kecil yang sering kelewat:

• Zawa nggak ngecek apakah nomor tujuan terdaftar di WhatsApp. Kalau nomornya nggak punya WhatsApp, kamu tetap dapet messageId, tapi pesannya nggak bakal nyampe ke mana-mana.
• Kirim ke channel cuma bisa ke channel yang kamu kelola (isOwner: true di Ambil Channel).
• Kalau kamu isi lebih dari satu kolom tujuan, yang dipakai urutannya group, lalu newsletter, lalu phone.

Kirim Media dari URL

Zawa nggak nerima upload file. Kamu cukup kasih URL, nanti Zawa yang download terus kirim ke WhatsApp. Biar lancar:

• URL harus publik dan langsung mengarah ke file-nya, bisa dibuka tanpa login. Link halaman preview (misalnya halaman share Google Drive) nggak bakal jalan.
• Pakai format yang aman. Zawa ngirim gambar sebagai JPEG, video sebagai MP4, dan audio sebagai MP3. Pakai file sumber dengan format itu biar hasilnya nggak aneh.
• mimetype tetap wajib diisi, misalnya image/jpeg, video/mp4, audio/mpeg, atau application/pdf.
• Thumbnail itu opsional. Kalau thumbnail dikosongin, gambar dan video pakai thumbnail bawaan Zawa. Khusus status video, thumbnail dibikin otomatis dari videonya.

Ada juga batas waktunya:

Batas	Nilai
Server file harus mulai ngirim data	60 detik
Download macet (nggak ada data masuk)	30 detik
Total proses kirim satu pesan atau status	4 menit
Ukuran body JSON	25 MB

Format Response

Kalau berhasil, kamu dapet status 200 dengan objek JSON. Endpoint yang ngembaliin daftar selalu bungkus datanya di docs:

{
  "docs": [
    { "id": "[email protected]", "name": "Zawa Community" }
  ]
}

Kalau gagal, bentuknya selalu sama:

{
  "statusCode": 400,
  "message": "invalid header"
}

Kalau ada beberapa kolom yang salah sekaligus, pesan-pesannya digabung pakai baris baru (\n) di message. Daftar lengkap error dan cara ngatasinnya ada di Error & Solusi.

Batasan Lain yang Perlu Diingat

• Indikator mengetik dari Kirim Typing cuma tampil 5 detik.
• Ambil Pesan Channel ngambil 100 pesan per halaman.
• Zawa nggak nyimpen pesan masuk dan saat ini nggak punya webhook. Webhook versi lama udah deprecated.