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.
2. Menautkan nomor (QR)
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
- Nomor pribadi:
62xxxxxxxxxx@c.us(kode negara tanpa tanda+) - Grup:
xxxxxxxxxx@g.us, ambil dari webhook atau daftar grup
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
| Kode | Arti | Tindakan |
|---|---|---|
| 401 | API key tidak valid atau tidak dikirim | Periksa header Authorization |
| 403 | Key tidak berhak atas sesi tersebut | Gunakan Session ID dari workspace Anda |
| 400 | Body tidak valid, atau sesi belum siap | Pastikan status nomor ready |
| 404 | Sesi tidak ditemukan | Periksa Session ID |
| 429 | Terlalu banyak request | Beri jeda dan coba lagi |
Batasan yang perlu diketahui
- Tanpa batas pesan bulanan dari sisi kami, tetapi WhatsApp memberlakukan pembatasan sendiri pada nomor baru. Hangatkan nomor baru secara bertahap.
- Satu nomor untuk satu sesi. Jangan menautkan nomor yang sama dua kali, perangkat tertaut sebelumnya dapat dicabut.
- Pesan pertama ke kontak baru bisa tidak sampai walaupun API menjawab sukses; itu kebijakan WhatsApp, bukan kesalahan gateway.
- Jangan gunakan nomor utama. Gunakan nomor khusus untuk layanan ini.
Butuh bantuan? Email support@instantserver.dev.