Dokumentasi API baWA

REST API JSON untuk mengirim dan menerima pesan WhatsApp. Base URL: https://api-gateway.intelixstudio.tech

Mulai cepat

Daftar dan beli instance di dashboard. Simpan API token dan ID instance.
Setelah admin mengaktifkan pembayaran, buka instance dan scan QR dari WhatsApp (Perangkat tertaut).
Kirim pesan pertama dengan contoh di bawah.

Nomor tujuan memakai format internasional tanpa tanda plus, mis. 6281234567890. Untuk grup, pakai JID grup (1203...@g.us).

curl -X POST "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/messages/text" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"to":"6281234567890","text":"Halo dari baWA"}'

Autentikasi

Semua endpoint memakai header Authorization: Bearer TOKEN. Token instance hanya berlaku untuk instance-nya sendiri. Token dilihat sekali saat dibuat; buat ulang dari dashboard bila hilang. Jangan taruh token di aplikasi sisi klien (browser/mobile).

Hubungkan nomor

Ambil QR (JSON berisi png_base64, atau tambahkan ?format=png untuk gambar langsung). Kode QR berganti sekitar tiap 20 detik, jadi polling tiap beberapa detik. Respons 202 = belum siap, 409 = sudah terhubung.

curl -X GET "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/qr" \
  -H "Authorization: Bearer TOKEN_ANDA"

Alternatif tanpa QR: minta kode pairing 8 karakter lalu masukkan di WhatsApp (Tautkan dengan nomor telepon).

curl -X POST "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/pairing-code" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"phone":"6281234567890"}'

Status koneksi: GET /v1/instances/ID_INSTANCE/state menghasilkan connected, qr, connecting, atau disconnected. Endpoint lain: POST /restart dan POST /logout.

Kirim pesan

Respons sukses berisi id pesan WhatsApp dan timestamp. Status akhir (terkirim/dibaca) datang lewat webhook, atau cek GET /v1/instances/ID_INSTANCE/messages/ID_PESAN.

curl -X POST "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/messages/text" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"to":"6281234567890","text":"Kode OTP Anda: 482910"}'

Kirim media

Endpoint: /messages/image, /video, /audio, /document. Sertakan url (http/https publik) atau base64. Maksimal 16 MB. Opsional: caption, mimetype, filename (dokumen), ptt (audio sebagai voice note).

curl -X POST "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/messages/document" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"to":"6281234567890","url":"https://contoh.com/invoice.pdf","filename":"invoice.pdf","caption":"Invoice bulan ini"}'

Cek nomor

Periksa apakah nomor terdaftar di WhatsApp sebelum mengirim (maksimal 50 nomor per request).

curl -X POST "https://api-gateway.intelixstudio.tech/v1/instances/ID_INSTANCE/check-number" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"phones":["6281234567890","6289876543210"]}'

Webhook

Atur URL webhook di dashboard atau lewat PUT /v1/instances/ID_INSTANCE/webhook. Setiap event dikirim sebagai POST JSON dengan header X-Bawa-Event, X-Bawa-Delivery, X-Bawa-Timestamp, dan X-Bawa-Signature (sha256= + HMAC-SHA256 dari body mentah memakai secret webhook instance). Balas status 2xx; selain itu dicoba ulang setelah 1 mnt, 5 mnt, 30 mnt, 2 jam, 12 jam.

Event: message.received, message.status (delivered/read), instance.state, instance.qr.

{
  "event": "message.received",
  "instance_id": "in_9f2c1a7b03d4e5f6",
  "timestamp": 1760000000,
  "data": {
    "id": "3EB0A1B2C3D4",
    "chat": "6281234567890@s.whatsapp.net",
    "sender": "6281234567890@s.whatsapp.net",
    "from_me": false,
    "is_group": false,
    "push_name": "Budi",
    "type": "text",
    "text": "Halo",
    "timestamp": 1760000000
  }
}

Verifikasi tanda tangan di server Anda (gunakan body mentah, bukan hasil parse):

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.BAWA_WEBHOOK_SECRET;

// Penting: ambil body MENTAH, jangan sudah di-parse.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const got = req.get("X-Bawa-Signature") || "";
  const ok =
    got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString());
  console.log(event.event, event.data);
  res.sendStatus(200);
});

app.listen(3000);

Partner API (aplikasi internal)

Untuk aplikasi seperti LMS yang mengelola banyak tenant. Admin membuat partner dan memberi partner key (bwp_...). Aplikasi membuat satu instance per tenant secara otomatis. Panggilan berulang dengan external_ref yang sama mengembalikan instance yang sama (idempoten). Partner key juga bisa dipakai langsung ke semua endpoint /v1/instances/ID/* milik partner.

curl -X POST "https://api-gateway.intelixstudio.tech/partner/v1/instances" \
  -H "Authorization: Bearer PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"tenant-42","name":"Sekolah A","webhook_url":"https://lms.contoh.com/hooks/wa"}'

Endpoint lain: GET /partner/v1/instances?external_ref=..., GET|DELETE /partner/v1/instances/ID, POST /partner/v1/instances/ID/rotate-token.

Error dan batas

Error berbentuk { "error": "pesan" } dengan status HTTP:

400 parameter tidak valid
401 token salah/tidak ada
403 instance tidak aktif (belum dibayar, kedaluwarsa, atau ditangguhkan)
404 instance/pesan tidak ditemukan
409 instance belum terhubung ke WhatsApp
429 batas pesan harian tercapai
502/504 gangguan komunikasi dengan WhatsApp

Batas pesan per hari mengikuti paket instance. Server menambahkan jeda acak 1-3 detik antar pesan per instance untuk mengurangi risiko pemblokiran, jadi request kirim bisa memakan waktu beberapa detik. Kirim pesan hanya ke kontak yang menyetujui; spam bisa membuat nomor diblokir WhatsApp.