WhatsApp Unofficial Gateway API

Setiap permintaan menyertakan header X-API-Key berisi API key penuh Anda (format jo_live_<…>). Bukan bearer token.

curl https://wau.jasaonline.net/v1/ping \
  -H "X-API-Key: jo_live_xxxxxxxx_xxxxxxxx…"

Key tidak valid atau dicabut → 401 unauthorized. Tenant ditangguhkan → 403 tenant_suspended. Key disimpan sebagai hash (argon2id) — simpan baik-baik saat dibuat, tidak dapat ditampilkan ulang oleh gateway (portal menyimpan salinan terenkripsi untuk Anda).

Batas default 60 permintaan/menit per key. Jika terlampaui → 429 rate_limit_exceeded disertai header Retry-After: 60.

Untuk mencegah duplikasi saat retry, sertakan header Idempotency-Key yang unik per operasi. Respons yang diputar ulang membawa Idempotent-Replay: true.

Sebuah "device" = satu nomor WhatsApp yang tertaut. Siklus statusnya:

NEW → PAIRING → ACTIVE → DISCONNECTED | LOGGED_OUT | BANNED

Buat device, mulai pairing, lalu pindai QR (PNG di /pair/qr.png, atau stream SSE di /pair/stream). QR berotasi ~20 detik.

Pakai portal kami jika Anda tidak ingin membangun UI pairing sendiri.

curl -X POST https://wau.jasaonline.net/v1/messages \
  -H "X-API-Key: jo_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "6281234567890",
    "type": "text",
    "text": "Halo dari gateway"
  }'

Nomor to boleh berupa digit polos (otomatis ditambah @s.whatsapp.net) atau JID grup …@g.us. Sukses → 202 Accepted:

{
  "message_id": "…",
  "wa_message_id": "…",
  "status": "queued",
  "device_id": "…"
}

Nomor pengirim & round-robin

Anda tidak mengirim daftar nomor pengirim — tidak ada field from. Pemilihan device diatur oleh satu field opsional device_id:

• Kosongkan device_id → gateway memilih otomatis. Untuk chat pribadi, percakapan baru disebar (round-robin) ke device aktif yang paling lama tak dipakai, lalu percakapan itu menempel ke device tersebut agar penerima selalu melihat nomor yang sama. Untuk grup, dipilih device yang menjadi anggota grup itu.
• Isi device_id: "<uuid>" → paksa satu device tertentu (harus berstatus ACTIVE). Ambil id dari GET /v1/devices.

Jadi round-robin lintas semua nomor aktif terjadi dengan sendirinya saat device_id dikosongkan; device_idhanya dipakai bila Anda ingin memilih satu pengirim spesifik. Respons & webhook selalu menyertakan device_id yang benar-benar dipakai.

Tipe yang didukung: text, image, video, audio, document, sticker, location, contact, reaction, edit, delete. Media memakai media_id (unggah dulu, lihat bagian Media) + caption. Reaction & delete memakai target_id. Lintas-tipe: reply_to, mentions, ttl, dan callback_url per-pesan.

Unggah via multipart/form-data (field file) atau JSON {"url": "…"}. Respons berisi media_id yang dipakai saat mengirim pesan media.

curl -X POST https://wau.jasaonline.net/v1/media \
  -H "X-API-Key: jo_live_…" \
  -F "file=@foto.jpg"
# → { "media_id": "…", "mime_type": "image/jpeg", "size_bytes": 12345 }

Daftarkan URL untuk menerima event. secret hanya dikembalikan sekali (saat create / rotate-secret). Event yang tersedia: message.received & message.status.

Verifikasi tanda tangan (WAJIB)

Setiap kiriman membawa header X-JO-Signature, X-JO-Timestamp, dan X-JO-Event-Id. Tanda tangan = HMAC-SHA256 atas timestamp + "." + rawBody:

import crypto from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-jo-timestamp"];
  const sig = req.headers["x-jo-signature"]; // "sha256=<hex>"
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(ts + "." + req.rawBody)   // rawBody = bytes mentah, bukan JSON re-serialize
      .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Balas 2xx untuk menandai sukses. Jika gagal, gateway mengulang dengan jadwal 0s · 30s · 2m · 10m · 1h · 6h · 24h, lalu berhenti (dead). Lima kegagalan beruntun membuka circuit breaker ~60 detik.

message.received

{
  "event": "message.received",
  "data": {
    "message_id": "…",
    "wa_message_id": "…",
    "device_id": "…",
    "chat_jid": "6281…@s.whatsapp.net",
    "sender_jid": "6281…@s.whatsapp.net",
    "is_group": false,
    "type": "text",
    "body": { "text": "isi pesan" },
    "media": { "media_id": "…", "url": "/v1/media/…" }
  }
}

media.url adalah path relatif — gabungkan dengan base URL untuk mengunduhnya (https://wau.jasaonline.net/v1/media/…). Bentuk body berbeda per tipe (mis. image → caption/mime; location → latitude/longitude).

message.status

{
  "event": "message.status",
  "data": {
    "message_id": "…",
    "wa_message_id": "…",
    "to": "6281…@s.whatsapp.net",
    "status": "delivered",           // sent | delivered | read | played | failed | expired
    "status_detail": "…"             // ada saat failed/expired
  }
}

Tersedia set lengkap untuk grup (/v1/groups/*: join, info, participants, invite-link, leave), chat (/v1/chats/*: mute, archive, read, disappearing, typing, history), dan kontak (/v1/contacts/*: check, block, info, avatar, presence, business). Semua memakai auth & konvensi yang sama.

GET /v1/contacts/check?phones=628xx,629xx mengecek apakah nomor terdaftar di WhatsApp — berguna sebelum mengirim massal.