IS Instant Server

WhatsApp Gateway API

Untuk pelanggan paket WA Starter, WA Business, dan WA Scale. Base URL, API key, dan Session ID untuk workspace Anda ada di halaman layanan pada panel billing.

Penting: gateway ini menjalankan sesi WhatsApp Web pada nomor Anda sendiri, bukan WhatsApp Cloud API resmi dari Meta. Pesan dikirim dari nomor yang Anda tautkan lewat scan QR. Tidak ada jaminan pengiriman dari WhatsApp dan tidak ada tombol autofill OTP otomatis, untuk OTP yang kritis, sediakan jalur cadangan (SMS atau email).

1. Autentikasi

Semua panggilan API memakai host https://wa-api.instantserver.dev. Dashboard admin gateway berada di host lain dan hanya untuk internal kami, Anda tidak perlu akses ke sana.

Setiap request memakai header Authorization dengan API key workspace Anda. Kunci ini hanya berlaku untuk nomor di workspace Anda; request ke nomor pelanggan lain ditolak dengan 403.

Authorization: Bearer owa_k1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Jangan menaruh API key di kode frontend atau repositori publik. Simpan sebagai environment variable di server Anda.

Nomor ditautkan sekali, dari halaman layanan di panel billing: buka Layanan → WhatsApp → Hubungkan, lalu scan QR dengan WhatsApp di HP (Perangkat tertaut → Tautkan perangkat). Setelah status menjadi ready, nomor siap dipakai lewat API.

Status setiap nomor bisa dibaca kapan saja:

GET/api/sessions/{sessionId}

{
  "id": "b0370086-9050-40ff-aa45-3f0034e26738",
  "name": "is27-my-business-1",
  "status": "ready",
  "phone": "6281234567890",
  "pushName": "Toko Saya"
}

3. Kirim pesan

POST/api/sessions/{sessionId}/messages/send-text

curl -X POST "https://wa-api.instantserver.dev/api/sessions/<SESSION_ID>/messages/send-text" \
  -H "Authorization: Bearer $OPENWA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"6281234567890@c.us","text":"Halo dari Instant Server"}'

Balasan berisi messageId dan timestamp:

{"messageId":"3EB0A1B2C3D4E5F6","timestamp":1761150000}

Format chatId

WhatsApp kadang mengirim ID pengirim dalam format <angka>@lid yang bukan nomor telepon. Untuk percakapan dua arah, selalu simpan chatId yang diterima dari webhook, jangan menyusunnya ulang dari nomor HP.

Contoh Node.js

const res = await fetch(
  `https://wa-api.instantserver.dev/api/sessions/${process.env.WA_SESSION_ID}/messages/send-text`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ chatId: '6281234567890@c.us', text: 'Halo!' }),
  }
);
console.log(await res.json());

Contoh PHP

$ch = curl_init("https://wa-api.instantserver.dev/api/sessions/{$sessionId}/messages/send-text");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer {$apiKey}",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'chatId' => '6281234567890@c.us',
        'text'   => 'Halo!',
    ]),
]);
echo curl_exec($ch);

4. Baca pesan masuk

GET/api/sessions/{sessionId}/messages?limit=50

Mengembalikan pesan terakhir untuk sesi tersebut. Untuk pemrosesan real-time, gunakan webhook di bagian berikutnya.

5. Webhook

Webhook dikonfigurasi per workspace oleh kami. Kirimkan URL penerima Anda, dan kami mendaftarkannya pada sesi Anda. Setiap pengiriman membawa signature:

X-OpenWA-Signature: sha256=<hex>
X-OpenWA-Idempotency-Key: <uuid>

Signature adalah HMAC-SHA256 dari body mentah dengan secret webhook Anda. Verifikasi sebelum memproses, dan dedupe berdasarkan idempotency key.

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Payload data adalah pesan dari engine WhatsApp, bukan baris database gateway. Gunakan fromMe dan isGroup untuk menentukan arah pesan, tidak ada field direction di payload.

6. Statistik pemakaian

GET/api/stats/sessions/{sessionId}

{
  "session": { "id": "...", "name": "is27-my-business-1", "status": "ready" },
  "messages": { "sent": 128, "received": 96, "today": 14, "failed": 2 }
}

7. Kode error

KodeArtiTindakan
401API key tidak valid atau tidak dikirimPeriksa header Authorization
403Key tidak berhak atas sesi tersebutGunakan Session ID dari workspace Anda
400Body tidak valid, atau sesi belum siapPastikan status nomor ready
404Sesi tidak ditemukanPeriksa Session ID
429Terlalu banyak requestBeri jeda dan coba lagi

Batasan yang perlu diketahui

Butuh bantuan? Email support@instantserver.dev.