Dokumentasi API

Pengantar

Baleswa adalah WhatsApp Gateway API: kirim & terima pesan WhatsApp lewat REST API sederhana. Semua endpoint mengembalikan JSON.

Base URLhttps://baleswa.com

FormatJSON (request & response)

ModeMulti-device

AuthBearer token / ?token=

Semua respons sukses berbentuk { "status": true, ... }. Respons gagal berbentuk { "status": false, "error": "..." }.

Butuh device terhubung dulu. Tambah device & scan QR di dashboard, lalu buat API key.

Autentikasi

Setiap request butuh API key. Tiga cara mengirimnya (pilih salah satu):

Authorization: Bearer YOUR_API_KEY (disarankan)
Authorization: YOUR_API_KEY (token mentah - kompatibel Fonnte)
Query string ?token=YOUR_API_KEY

Format key: live baleswa…, test baleswatest… (validasi tapi tidak benar-benar mengirim). Key lama bls_live_… / bls_test_… tetap berlaku. Limit ~60 request/menit per key untuk endpoint kirim.

Buat & cabut API key di tab API Key pada dashboard. Jaga kerahasiaannya - siapa pun dengan key ini bisa mengirim pesan atas namamu.

Quick Start

Kirim pesan WhatsApp pertama dalam satu request:

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "628123456789",
    "message": "Halo dari Baleswa 👋"
  }'

Ganti YOUR_API_KEY dengan key milikmu. target = nomor tujuan format 62... (tanpa + dan tanpa 0 di depan).

Kirim Pesan

POST/api/v1/send

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx. Untuk bulk, pisahkan dengan koma.
`message`	string	Ya*	Isi pesan teks. *Wajib jika tanpa mediaUrl.
`device`	string	Tidak	Nama/ID device. Kosong = device terhubung pertama.
`mediaUrl`	string	Tidak	URL publik gambar/file untuk dikirim.
`mediaType`	string	Tidak	"image" untuk gambar, "file" untuk dokumen.
`filename`	string	Tidak	Nama file (untuk dokumen).
`delay`	string	Tidak	Jeda antar pesan saat bulk, mis. "5" atau "5-10" (detik, acak).

Contoh

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "628123456789",
    "message": "Halo dari Baleswa 👋"
  }'

Response sukses

json

{
  "status": true,
  "detail": "1 pesan masuk antrian",
  "id": ["[email protected]_3EB0..."],
  "process": "sent",
  "device": "CS Utama",
  "target": ["628123456789"]
}

Kirim Media & File

Tambahkan mediaUrl (URL publik). Untuk gambar set mediaType=image; untuk dokumen set mediaType=file.

bash

# Gambar (dengan caption)
curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "message": "Brosur promo bulan ini",
    "mediaUrl": "https://contoh.com/promo.jpg",
    "mediaType": "image"
  }'

# Dokumen (PDF, dll)
curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "mediaUrl": "https://contoh.com/invoice.pdf",
    "mediaType": "file",
    "filename": "invoice-001.pdf"
  }'

Bulk / Broadcast

Kirim ke banyak nomor sekaligus: pisahkan target dengan koma. Gunakan delay agar ada jeda acak antar pesan (mengurangi risiko banned).

bash

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628111111111,628222222222,628333333333",
    "message": "Halo, ada promo spesial untukmu!",
    "delay": "5-10"
  }'

Untuk volume besar, kirim per-batch dan beri jeda. Lihat Tips Anti-Banned.

Kirim Lokasi

POST/api/v1/send/location

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`latitude`	number	Ya	Garis lintang, mis. -6.2088.
`longitude`	number	Ya	Garis bujur, mis. 106.8456.
`title`	string	Tidak	Label lokasi yang tampil di pesan.

bash

curl -X POST https://baleswa.com/api/v1/send/location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "latitude": -6.2088,
    "longitude": 106.8456,
    "title": "Kantor Pusat"
  }'

Kirim Polling

POST/api/v1/send/poll

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`name`	string	Ya	Pertanyaan / judul polling.
`options`	string[]	Ya	Daftar pilihan jawaban (minimal 2).
`multipleAnswers`	boolean	Tidak	true = boleh pilih lebih dari satu.

bash

curl -X POST https://baleswa.com/api/v1/send/poll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "name": "Jam meeting paling cocok?",
    "options": ["09.00", "13.00", "16.00"],
    "multipleAnswers": false
  }'

Kirim Kontak

POST/api/v1/send/contact

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`name`	string	Ya	Nama kontak yang dikirim.
`phone`	string	Ya	Nomor kontak format 62xxx.

bash

curl -X POST https://baleswa.com/api/v1/send/contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "name": "Tim Support",
    "phone": "628999888777"
  }'

Kirim Voice Note

POST/api/v1/send/voice

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`url`	string	Ya	URL publik file audio (mp3/ogg).

bash

curl -X POST https://baleswa.com/api/v1/send/voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "url": "https://contoh.com/pesan-suara.ogg"
  }'

Kirim Video

POST/api/v1/send/video

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`url`	string	Ya	URL publik file video (mp4).
`caption`	string	Tidak	Teks keterangan video.

bash

curl -X POST https://baleswa.com/api/v1/send/video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "url": "https://contoh.com/demo.mp4",
    "caption": "Tutorial singkat produk kami"
  }'

Typing Indicator

POST/api/v1/typing

Tampilkan/sembunyikan status "sedang mengetik" ke lawan chat.

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`action`	string	Ya	"start" mulai mengetik, "stop" berhenti.

bash

curl -X POST https://baleswa.com/api/v1/typing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "action": "start"
  }'

Tandai Dibaca

POST/api/v1/seen

Tandai pesan dari lawan chat sebagai sudah dibaca (centang biru).

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Tidak	ID pesan tertentu. Kosong = tandai chat.

bash

curl -X POST https://baleswa.com/api/v1/seen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0..."
  }'

Reaksi Pesan

POST/api/v1/reaction

Beri reaksi emoji ke sebuah pesan. Kirim emoji kosong ("") untuk menghapus reaksi.

Parameter

Parameter	Tipe	Wajib	Keterangan
`messageId`	string	Ya	ID pesan yang ingin direaksi.
`emoji`	string	Ya	Emoji reaksi, mis. "👍". Kosong = hapus reaksi.

bash

curl -X POST https://baleswa.com/api/v1/reaction \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messageId": "[email protected]_3EB0...",
    "emoji": "👍"
  }'

Teruskan Pesan

POST/api/v1/message/forward

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`messageId`	string	Ya	ID pesan yang diteruskan.

bash

curl -X POST https://baleswa.com/api/v1/message/forward \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628999888777",
    "messageId": "[email protected]_3EB0..."
  }'

Edit Pesan

POST/api/v1/message/edit

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Ya	ID pesan yang diedit (harus pesan keluar).
`text`	string	Ya	Teks baru pengganti isi pesan.

bash

curl -X POST https://baleswa.com/api/v1/message/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0...",
    "text": "Maaf, harga sudah diperbarui jadi Rp150.000"
  }'

Hapus Pesan

POST/api/v1/message/delete

Hapus pesan keluar untuk semua orang (delete for everyone).

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Ya	ID pesan yang dihapus (harus pesan keluar).

bash

curl -X POST https://baleswa.com/api/v1/message/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0..."
  }'

Status Pengiriman

GET/api/v1/message/status

Cek status pengiriman sebuah pesan keluar (sent, delivered, read, failed).

Parameter (query)

Parameter	Tipe	Wajib	Keterangan
`id`	string	Ya	WhatsApp message id, dari field id pada respons /send.

bash

curl "https://baleswa.com/api/v1/message/[email protected]_3EB0..." \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "id": "[email protected]_3EB0...",
  "device": "CS Utama",
  "deliveryStatus": "delivered",
  "to": "628123456789",
  "ackAt": "2026-06-26T10:00:05.000Z",
  "sentAt": "2026-06-26T10:00:00.000Z"
}

Inbox / Daftar Pesan

GET/api/v1/messages

Ambil daftar pesan (default pesan masuk). Buat polling inbox tanpa webhook.

Parameter (query)

Parameter	Tipe	Wajib	Keterangan
`direction`	string	Tidak	in (default) \| out \| all.
`limit`	number	Tidak	Default 30, maks 200.
`device`	string	Tidak	ID/nama device tertentu.
`since`	string	Tidak	ISO timestamp, ambil yang lebih baru.
`group`	0/1	Tidak	1 untuk ikutkan pesan grup.

bash

curl "https://baleswa.com/api/v1/messages?direction=in&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Upload Media

POST/api/v1/media

Upload file (maks 16 MB) lalu pakai URL hasilnya sebagai mediaUrl di /send. Berguna kalau file belum punya URL publik.

Form-data

Parameter	Tipe	Wajib	Keterangan
`file`	file	Ya	File yang diupload (multipart/form-data, maks 16 MB).

bash

curl -X POST https://baleswa.com/api/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"
# -> { "status": true, "url": "...", "name": "brosur.jpg", "mime": "image/jpeg", "size": 12345 }

Grup

Lihat daftar grup atau buat grup baru.

GET/api/v1/groups

bash

curl https://baleswa.com/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "groups": [
    { "id": "[email protected]", "name": "Tim Sales", "participants": 12 }
  ]
}

POST/api/v1/groups

Parameter (buat grup)

Parameter	Tipe	Wajib	Keterangan
`name`	string	Ya	Nama grup baru.
`participants`	string[]	Ya	Daftar nomor anggota awal (62xxx).

bash

curl -X POST https://baleswa.com/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Tim Proyek A",
    "participants": ["628111111111", "628222222222"]
  }'

Anggota Grup

POST/api/v1/groups/participants

Kelola anggota grup: tambah, keluarkan, jadikan admin, atau cabut admin.

Parameter

Parameter	Tipe	Wajib	Keterangan
`groupId`	string	Ya	ID grup, mis. [email protected].
`action`	string	Ya	"add", "remove", "promote", atau "demote".
`participants`	string[]	Ya	Daftar nomor yang dikenai aksi (62xxx).

bash

curl -X POST https://baleswa.com/api/v1/groups/participants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "groupId": "[email protected]",
    "action": "add",
    "participants": ["628333333333"]
  }'

Cek Nomor WhatsApp

GET/api/v1/contacts/check

Cek apakah sebuah nomor terdaftar di WhatsApp.

Parameter (query string)

Parameter	Tipe	Wajib	Keterangan
`phone`	string	Ya	Nomor yang dicek, format 62xxx.

bash

curl "https://baleswa.com/api/v1/contacts/check?phone=628123456789" \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "phone": "628123456789",
  "exists": true
}

OTP

Kirim & verifikasi kode OTP lewat WhatsApp. Kode di-generate server-side dan punya masa berlaku.

POST/api/v1/otp/send

Parameter (kirim)

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`length`	number	Tidak	Panjang kode (default 6).
`template`	string	Tidak	Template pesan, gunakan {code} sebagai placeholder.

bash

curl -X POST https://baleswa.com/api/v1/otp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "length": 6,
    "template": "Kode verifikasi kamu: {code}"
  }'

POST/api/v1/otp/verify

Parameter (verifikasi)

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`code`	string	Ya	Kode OTP yang diterima pengguna.

bash

curl -X POST https://baleswa.com/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "code": "123456"
  }'

json

{ "status": true, "verified": true, "detail": "OTP valid" }

Daftar Device

GET/api/v1/devices

Cek status koneksi semua device milikmu.

bash

curl https://baleswa.com/api/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "devices": [
    { "name": "CS Utama", "phoneNumber": "628...", "status": "connected", "messageCount": 1240 }
  ]
}

Webhook - Pesan Masuk

Setiap device bisa diberi URL webhook (atur saat tambah device). Saat ada pesan masuk, Baleswa mengirim HTTP POST ke URL-mu:

json

{
  "device": "CS Utama",
  "from": "628123456789",
  "body": "halo, mau tanya stok",
  "type": "text",
  "timestamp": 1750000000,
  "id": "[email protected]_3EB0..."
}

Header tiap request

X-Baleswa-Event - jenis event: message, message.ack, dll.
X-Baleswa-Signature: sha256=<hex> - hanya jika device punya signing secret. HMAC-SHA256 dari body mentah pakai secret itu. Verifikasi sebelum dipercaya.

Event status pengiriman (message.ack)

json

{ "device": "CS Utama", "event": "message.ack", "id": "[email protected]_3EB0...", "status": "delivered" }

Verifikasi signature (Node)

javascript

import crypto from "crypto";
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-baleswa-signature"] || "";
  const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");
  if (sig && !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.status(401).end();
  const evt = JSON.parse(req.body.toString());
  // proses dengan LLM milikmu sendiri (Baleswa tidak menyediakan AI bawaan)
  res.json({ ok: true });
});

Webhook harus selalu balas cepat (mis. 200 OK). Lakukan proses berat (LLM, DB) secara async. Pengiriman yang gagal di-retry sekali, dan tiap percobaan tercatat di halaman Webhook.

Kode Error

Error mengembalikan { "status": false, "error": "..." } dengan kode HTTP:

HTTP	Arti	Penyebab umum
`400`	Bad Request	parameter wajib kosong / tidak valid
`401`	Unauthorized	API key salah / dicabut / tidak dikirim
`404`	Not Found	device / pesan / grup yang diminta tidak ditemukan
`409`	Conflict	device belum terhubung (perlu scan QR)
`422`	Unprocessable	format parameter salah (mis. options polling < 2)
`429`	Too Many Requests	melebihi 60 request/menit per key (tunggu sebentar)
`502`	Bad Gateway	engine gagal memproses permintaan

Migrasi dari Fonnte / Wablas

API Baleswa sengaja dibuat mirip Fonnte agar mudah pindah. Pemetaan parameter:

Fonnte	Baleswa	Catatan
`target`	target	Sama. Koma untuk bulk.
`message`	message	Sama.
`url`	mediaUrl	URL media (alias url juga diterima).
`delay`	delay	Sama, format "5-10".
`Authorization: TOKEN`	Authorization: KEY	Token mentah tetap diterima.

Banyak kode lama Fonnte bisa jalan cukup dengan mengganti base URL & token. Endpoint lanjutan (lokasi, polling, grup, OTP) adalah tambahan Baleswa.

Tips Anti-Banned

Pakai nomor yang sudah lama aktif, jangan nomor baru untuk blast.
Beri delay acak (mis. 5-15) saat bulk; hindari ribuan pesan sekaligus.
Kirim hanya ke orang yang mengenal/menunggu pesanmu (notifikasi, OTP, balasan).
Variasikan isi pesan; hindari teks identik massal.
Hangatkan nomor baru: chat normal beberapa hari sebelum dipakai API.

Jaga pola pengiriman tetap wajar agar nomor aman dari pemblokiran WhatsApp. Pola kirim yang menentukan, bukan API-nya.

Siap mencoba langsung?

Buka Playground

Pengantar

Baleswa adalah WhatsApp Gateway API: kirim & terima pesan WhatsApp lewat REST API sederhana. Semua endpoint mengembalikan JSON.

Base URLhttps://baleswa.com

FormatJSON (request & response)

ModeMulti-device

AuthBearer token / ?token=

Semua respons sukses berbentuk { "status": true, ... }. Respons gagal berbentuk { "status": false, "error": "..." }.

Butuh device terhubung dulu. Tambah device & scan QR di dashboard, lalu buat API key.

Autentikasi

Setiap request butuh API key. Tiga cara mengirimnya (pilih salah satu):

Authorization: Bearer YOUR_API_KEY (disarankan)
Authorization: YOUR_API_KEY (token mentah - kompatibel Fonnte)
Query string ?token=YOUR_API_KEY

Buat & cabut API key di tab API Key pada dashboard. Jaga kerahasiaannya - siapa pun dengan key ini bisa mengirim pesan atas namamu.

Quick Start

Kirim pesan WhatsApp pertama dalam satu request:

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "628123456789",
    "message": "Halo dari Baleswa 👋"
  }'

Ganti YOUR_API_KEY dengan key milikmu. target = nomor tujuan format 62... (tanpa + dan tanpa 0 di depan).

Kirim Pesan

POST/api/v1/send

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx. Untuk bulk, pisahkan dengan koma.
`message`	string	Ya*	Isi pesan teks. *Wajib jika tanpa mediaUrl.
`device`	string	Tidak	Nama/ID device. Kosong = device terhubung pertama.
`mediaUrl`	string	Tidak	URL publik gambar/file untuk dikirim.
`mediaType`	string	Tidak	"image" untuk gambar, "file" untuk dokumen.
`filename`	string	Tidak	Nama file (untuk dokumen).
`delay`	string	Tidak	Jeda antar pesan saat bulk, mis. "5" atau "5-10" (detik, acak).

Contoh

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "628123456789",
    "message": "Halo dari Baleswa 👋"
  }'

Response sukses

json

{
  "status": true,
  "detail": "1 pesan masuk antrian",
  "id": ["[email protected]_3EB0..."],
  "process": "sent",
  "device": "CS Utama",
  "target": ["628123456789"]
}

Kirim Media & File

Tambahkan mediaUrl (URL publik). Untuk gambar set mediaType=image; untuk dokumen set mediaType=file.

bash

# Gambar (dengan caption)
curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "message": "Brosur promo bulan ini",
    "mediaUrl": "https://contoh.com/promo.jpg",
    "mediaType": "image"
  }'

# Dokumen (PDF, dll)
curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "mediaUrl": "https://contoh.com/invoice.pdf",
    "mediaType": "file",
    "filename": "invoice-001.pdf"
  }'

Bulk / Broadcast

Kirim ke banyak nomor sekaligus: pisahkan target dengan koma. Gunakan delay agar ada jeda acak antar pesan (mengurangi risiko banned).

bash

curl -X POST https://baleswa.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628111111111,628222222222,628333333333",
    "message": "Halo, ada promo spesial untukmu!",
    "delay": "5-10"
  }'

Untuk volume besar, kirim per-batch dan beri jeda. Lihat Tips Anti-Banned.

Kirim Lokasi

POST/api/v1/send/location

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`latitude`	number	Ya	Garis lintang, mis. -6.2088.
`longitude`	number	Ya	Garis bujur, mis. 106.8456.
`title`	string	Tidak	Label lokasi yang tampil di pesan.

bash

curl -X POST https://baleswa.com/api/v1/send/location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "latitude": -6.2088,
    "longitude": 106.8456,
    "title": "Kantor Pusat"
  }'

Kirim Polling

POST/api/v1/send/poll

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`name`	string	Ya	Pertanyaan / judul polling.
`options`	string[]	Ya	Daftar pilihan jawaban (minimal 2).
`multipleAnswers`	boolean	Tidak	true = boleh pilih lebih dari satu.

bash

curl -X POST https://baleswa.com/api/v1/send/poll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "name": "Jam meeting paling cocok?",
    "options": ["09.00", "13.00", "16.00"],
    "multipleAnswers": false
  }'

Kirim Kontak

POST/api/v1/send/contact

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`name`	string	Ya	Nama kontak yang dikirim.
`phone`	string	Ya	Nomor kontak format 62xxx.

bash

curl -X POST https://baleswa.com/api/v1/send/contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "name": "Tim Support",
    "phone": "628999888777"
  }'

Kirim Voice Note

POST/api/v1/send/voice

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`url`	string	Ya	URL publik file audio (mp3/ogg).

bash

curl -X POST https://baleswa.com/api/v1/send/voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "url": "https://contoh.com/pesan-suara.ogg"
  }'

Kirim Video

POST/api/v1/send/video

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`url`	string	Ya	URL publik file video (mp4).
`caption`	string	Tidak	Teks keterangan video.

bash

curl -X POST https://baleswa.com/api/v1/send/video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "url": "https://contoh.com/demo.mp4",
    "caption": "Tutorial singkat produk kami"
  }'

Typing Indicator

POST/api/v1/typing

Tampilkan/sembunyikan status "sedang mengetik" ke lawan chat.

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`action`	string	Ya	"start" mulai mengetik, "stop" berhenti.

bash

curl -X POST https://baleswa.com/api/v1/typing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "action": "start"
  }'

Tandai Dibaca

POST/api/v1/seen

Tandai pesan dari lawan chat sebagai sudah dibaca (centang biru).

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Tidak	ID pesan tertentu. Kosong = tandai chat.

bash

curl -X POST https://baleswa.com/api/v1/seen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0..."
  }'

Reaksi Pesan

POST/api/v1/reaction

Beri reaksi emoji ke sebuah pesan. Kirim emoji kosong ("") untuk menghapus reaksi.

Parameter

Parameter	Tipe	Wajib	Keterangan
`messageId`	string	Ya	ID pesan yang ingin direaksi.
`emoji`	string	Ya	Emoji reaksi, mis. "👍". Kosong = hapus reaksi.

bash

curl -X POST https://baleswa.com/api/v1/reaction \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messageId": "[email protected]_3EB0...",
    "emoji": "👍"
  }'

Teruskan Pesan

POST/api/v1/message/forward

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`messageId`	string	Ya	ID pesan yang diteruskan.

bash

curl -X POST https://baleswa.com/api/v1/message/forward \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628999888777",
    "messageId": "[email protected]_3EB0..."
  }'

Edit Pesan

POST/api/v1/message/edit

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Ya	ID pesan yang diedit (harus pesan keluar).
`text`	string	Ya	Teks baru pengganti isi pesan.

bash

curl -X POST https://baleswa.com/api/v1/message/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0...",
    "text": "Maaf, harga sudah diperbarui jadi Rp150.000"
  }'

Hapus Pesan

POST/api/v1/message/delete

Hapus pesan keluar untuk semua orang (delete for everyone).

Parameter

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor chat 62xxx.
`messageId`	string	Ya	ID pesan yang dihapus (harus pesan keluar).

bash

curl -X POST https://baleswa.com/api/v1/message/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "messageId": "[email protected]_3EB0..."
  }'

Status Pengiriman

GET/api/v1/message/status

Cek status pengiriman sebuah pesan keluar (sent, delivered, read, failed).

Parameter (query)

Parameter	Tipe	Wajib	Keterangan
`id`	string	Ya	WhatsApp message id, dari field id pada respons /send.

bash

curl "https://baleswa.com/api/v1/message/[email protected]_3EB0..." \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "id": "[email protected]_3EB0...",
  "device": "CS Utama",
  "deliveryStatus": "delivered",
  "to": "628123456789",
  "ackAt": "2026-06-26T10:00:05.000Z",
  "sentAt": "2026-06-26T10:00:00.000Z"
}

Inbox / Daftar Pesan

GET/api/v1/messages

Ambil daftar pesan (default pesan masuk). Buat polling inbox tanpa webhook.

Parameter (query)

Parameter	Tipe	Wajib	Keterangan
`direction`	string	Tidak	in (default) \| out \| all.
`limit`	number	Tidak	Default 30, maks 200.
`device`	string	Tidak	ID/nama device tertentu.
`since`	string	Tidak	ISO timestamp, ambil yang lebih baru.
`group`	0/1	Tidak	1 untuk ikutkan pesan grup.

bash

curl "https://baleswa.com/api/v1/messages?direction=in&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Upload Media

POST/api/v1/media

Upload file (maks 16 MB) lalu pakai URL hasilnya sebagai mediaUrl di /send. Berguna kalau file belum punya URL publik.

Form-data

Parameter	Tipe	Wajib	Keterangan
`file`	file	Ya	File yang diupload (multipart/form-data, maks 16 MB).

bash

curl -X POST https://baleswa.com/api/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"
# -> { "status": true, "url": "...", "name": "brosur.jpg", "mime": "image/jpeg", "size": 12345 }

Grup

Lihat daftar grup atau buat grup baru.

GET/api/v1/groups

bash

curl https://baleswa.com/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "groups": [
    { "id": "[email protected]", "name": "Tim Sales", "participants": 12 }
  ]
}

POST/api/v1/groups

Parameter (buat grup)

Parameter	Tipe	Wajib	Keterangan
`name`	string	Ya	Nama grup baru.
`participants`	string[]	Ya	Daftar nomor anggota awal (62xxx).

bash

curl -X POST https://baleswa.com/api/v1/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Tim Proyek A",
    "participants": ["628111111111", "628222222222"]
  }'

Anggota Grup

POST/api/v1/groups/participants

Kelola anggota grup: tambah, keluarkan, jadikan admin, atau cabut admin.

Parameter

Parameter	Tipe	Wajib	Keterangan
`groupId`	string	Ya	ID grup, mis. [email protected].
`action`	string	Ya	"add", "remove", "promote", atau "demote".
`participants`	string[]	Ya	Daftar nomor yang dikenai aksi (62xxx).

bash

curl -X POST https://baleswa.com/api/v1/groups/participants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "groupId": "[email protected]",
    "action": "add",
    "participants": ["628333333333"]
  }'

Cek Nomor WhatsApp

GET/api/v1/contacts/check

Cek apakah sebuah nomor terdaftar di WhatsApp.

Parameter (query string)

Parameter	Tipe	Wajib	Keterangan
`phone`	string	Ya	Nomor yang dicek, format 62xxx.

bash

curl "https://baleswa.com/api/v1/contacts/check?phone=628123456789" \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "phone": "628123456789",
  "exists": true
}

OTP

Kirim & verifikasi kode OTP lewat WhatsApp. Kode di-generate server-side dan punya masa berlaku.

POST/api/v1/otp/send

Parameter (kirim)

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`length`	number	Tidak	Panjang kode (default 6).
`template`	string	Tidak	Template pesan, gunakan {code} sebagai placeholder.

bash

curl -X POST https://baleswa.com/api/v1/otp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "length": 6,
    "template": "Kode verifikasi kamu: {code}"
  }'

POST/api/v1/otp/verify

Parameter (verifikasi)

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Nomor tujuan 62xxx.
`code`	string	Ya	Kode OTP yang diterima pengguna.

bash

curl -X POST https://baleswa.com/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "target": "628123456789",
    "code": "123456"
  }'

json

{ "status": true, "verified": true, "detail": "OTP valid" }

Daftar Device

GET/api/v1/devices

Cek status koneksi semua device milikmu.

bash

curl https://baleswa.com/api/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "status": true,
  "devices": [
    { "name": "CS Utama", "phoneNumber": "628...", "status": "connected", "messageCount": 1240 }
  ]
}

Webhook - Pesan Masuk

Setiap device bisa diberi URL webhook (atur saat tambah device). Saat ada pesan masuk, Baleswa mengirim HTTP POST ke URL-mu:

json

{
  "device": "CS Utama",
  "from": "628123456789",
  "body": "halo, mau tanya stok",
  "type": "text",
  "timestamp": 1750000000,
  "id": "[email protected]_3EB0..."
}

Header tiap request

X-Baleswa-Event - jenis event: message, message.ack, dll.
X-Baleswa-Signature: sha256=<hex> - hanya jika device punya signing secret. HMAC-SHA256 dari body mentah pakai secret itu. Verifikasi sebelum dipercaya.

Event status pengiriman (message.ack)

json

{ "device": "CS Utama", "event": "message.ack", "id": "[email protected]_3EB0...", "status": "delivered" }

Verifikasi signature (Node)

javascript

import crypto from "crypto";
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-baleswa-signature"] || "";
  const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");
  if (sig && !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return res.status(401).end();
  const evt = JSON.parse(req.body.toString());
  // proses dengan LLM milikmu sendiri (Baleswa tidak menyediakan AI bawaan)
  res.json({ ok: true });
});

Webhook harus selalu balas cepat (mis. 200 OK). Lakukan proses berat (LLM, DB) secara async. Pengiriman yang gagal di-retry sekali, dan tiap percobaan tercatat di halaman Webhook.

Kode Error

Error mengembalikan { "status": false, "error": "..." } dengan kode HTTP:

HTTP	Arti	Penyebab umum
`400`	Bad Request	parameter wajib kosong / tidak valid
`401`	Unauthorized	API key salah / dicabut / tidak dikirim
`404`	Not Found	device / pesan / grup yang diminta tidak ditemukan
`409`	Conflict	device belum terhubung (perlu scan QR)
`422`	Unprocessable	format parameter salah (mis. options polling < 2)
`429`	Too Many Requests	melebihi 60 request/menit per key (tunggu sebentar)
`502`	Bad Gateway	engine gagal memproses permintaan

Migrasi dari Fonnte / Wablas

API Baleswa sengaja dibuat mirip Fonnte agar mudah pindah. Pemetaan parameter:

Fonnte	Baleswa	Catatan
`target`	target	Sama. Koma untuk bulk.
`message`	message	Sama.
`url`	mediaUrl	URL media (alias url juga diterima).
`delay`	delay	Sama, format "5-10".
`Authorization: TOKEN`	Authorization: KEY	Token mentah tetap diterima.

Banyak kode lama Fonnte bisa jalan cukup dengan mengganti base URL & token. Endpoint lanjutan (lokasi, polling, grup, OTP) adalah tambahan Baleswa.

Tips Anti-Banned

Pakai nomor yang sudah lama aktif, jangan nomor baru untuk blast.
Beri delay acak (mis. 5-15) saat bulk; hindari ribuan pesan sekaligus.
Kirim hanya ke orang yang mengenal/menunggu pesanmu (notifikasi, OTP, balasan).
Variasikan isi pesan; hindari teks identik massal.
Hangatkan nomor baru: chat normal beberapa hari sebelum dipakai API.

Jaga pola pengiriman tetap wajar agar nomor aman dari pemblokiran WhatsApp. Pola kirim yang menentukan, bukan API-nya.

Siap mencoba langsung?

Buka Playground