Dokumentasi API

Referensi lengkap WA Gateway API v2.1 — untuk developer yang mengintegrasikan notifikasi, OTP, reminder, dan broadcast WhatsApp ke aplikasinya.

1. Pengantar

Base URL	`https://wa.pgtm.biz.id`
Format	JSON (`Content-Type: application/json`) untuk request & response.
Envelope respons	Semua respons berisi `status` (boolean) dan `request_id`. Sukses menambah field sesuai endpoint; gagal berisi `code` + `reason` yang stabil untuk ditangani program.
Request ID	Dikirim juga sebagai header `X-Request-Id`. Sebutkan ID ini bila melaporkan masalah.
CORS	Diaktifkan untuk semua endpoint API (`Access-Control-Allow-Origin: *`). Token tetap rahasia — jangan ekspos di kode frontend publik.

// Contoh respons sukses
{ "status": true, "detail": "queued", "id": ["msg-9f2ac41bd207"], "accepted": 1, "rejected": 0, "request_id": "req-1a2b3c" }

// Contoh respons gagal
{ "status": false, "code": "TOKEN_INVALID", "reason": "token invalid", "request_id": "req-1a2b3c" }

2. Autentikasi

Dua jenis token, jangan tertukar:

Token	Untuk	Lokasi
Token device	/send, /validate, /device, /fetch-groups, /message/:id	Kartu device di dashboard
Token akun	/get-devices	Kartu "Token akun" di dashboard

curl https://wa.pgtm.biz.id/device -H "Authorization: Bearer TOKEN_DEVICE"

Prefiks Bearer opsional. Token juga dapat dikirim sebagai field token di body JSON (tidak disarankan — header lebih aman). Perlakukan token seperti password: bocor = regenerasi dari dashboard.

3. Endpoint

POST/send — kirim pesan

Mengirim teks, media, atau lokasi ke satu/banyak nomor dan grup. Pesan masuk antrean dan dikirim berurutan dengan jeda anti-spam (lihat Batas & perilaku).

Parameter	Tipe	Wajib	Keterangan
`target`	string	Ya	Satu atau banyak penerima dipisah koma. Nomor: format lokal `08xx` atau internasional `62xx`. Grup: ID berakhiran `@g.us` (ambil dari /fetch-groups). Nomor tak valid dihitung di field `rejected`.
`message`	string	Kondisional	Isi teks / caption media. Wajib kecuali mengirim lokasi murni. Kata "OTP" di pesan = jalur prioritas.
`url`	string (URL)	Tidak	URL publik gambar (jpg/png/webp), video (mp4), atau dokumen. Butuh paket berkmedia.
`schedule`	integer	Tidak	Unix timestamp (detik) — pesan dikirim pada waktu itu.
`delay`	integer	Tidak	Tunda N detik dari sekarang (alternatif `schedule`).
`latitude` + `longitude`	number	Tidak	Kirim titik lokasi (keduanya harus diisi).

curl -X POST https://wa.pgtm.biz.id/send \
  -H "Authorization: Bearer TOKEN_DEVICE" -H "Content-Type: application/json" \
  -d '{"target":"081234567890","message":"Halo, tagihan Anda sudah terbit."}'

{ "status": true, "detail": "queued", "id": ["msg-9f2ac41bd207"], "accepted": 1, "rejected": 0, "request_id": "req-1a2b3c" }

Simpan id untuk melacak status lewat GET /message/:id. detail = scheduled bila memakai schedule/delay.

GET/message/:id — status pesan

State	Arti
`queued`	Di antrean, menunggu giliran kirim.
`scheduled`	Menunggu jadwal (schedule/delay).
`sent`	Terkirim; `wa_id` berisi ID pesan WhatsApp.
`failed`	Gagal setelah percobaan ulang maksimal.
`not_found`	ID tidak dikenal (atau bukan milik device token ini).

curl https://wa.pgtm.biz.id/message/msg-9f2ac41bd207 -H "Authorization: Bearer TOKEN_DEVICE"
// → { "status": true, "data": { "id": "msg-9f2ac41bd207", "state": "sent", "to": "6281234567890", "wa_id": "3EB0A1B2C3" }, "request_id": "req-…" }

POST/validate — cek nomor WhatsApp

curl -X POST https://wa.pgtm.biz.id/validate -H "Authorization: Bearer TOKEN_DEVICE" -H "Content-Type: application/json" -d '{"target":"081234567890,081298765432"}'
// → { "status": true, "detail": "ok", "result": [ { "target": "081234567890", "registered": true } ], "request_id": "req-…" }

Device harus terhubung; bila tidak, respons DEVICE_OFFLINE.

GET/device — profil device

Status koneksi, nomor terhubung, paket, sisa kuota, dan masa aktif pemilik token device.

POST/fetch-groups — daftar grup

Mengembalikan groups: [{id: "…@g.us", name}] dari grup yang diikuti device. Juga tersedia via GET.

GET/get-devices — semua device akun

Memakai token akun. Mengembalikan profil akun (paket & kuota) + daftar device beserta status koneksinya.

GET/health — status layanan

Tanpa autentikasi: jumlah device, device online, dan panjang antrean.

4. Contoh kode — POST /send

PHP (cURL)

$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://wa.pgtm.biz.id/send',
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer TOKEN_DEVICE', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['target' => '081234567890', 'message' => 'Halo dari PHP']),
]);
echo curl_exec($curl);

Node.js (fetch)

const res = await fetch('https://wa.pgtm.biz.id/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TOKEN_DEVICE', 'Content-Type': 'application/json' },
  body: JSON.stringify({ target: '081234567890', message: 'Halo dari Node.js' }),
});
console.log(await res.json());

Python (requests)

import requests
r = requests.post('https://wa.pgtm.biz.id/send',
  headers={'Authorization': 'Bearer TOKEN_DEVICE'},
  json={'target': '081234567890', 'message': 'Halo dari Python'})
print(r.json())

5. Webhook pesan masuk

Isi Webhook URL di dashboard. Setiap pesan masuk diteruskan (POST JSON) ke URL tersebut:

Field	Keterangan
`event`	Selalu `"incoming"`.
`device`	ID device penerima.
`from`	JID pengirim (`…@s.whatsapp.net` atau `…@g.us` untuk grup).
`id`	ID pesan WhatsApp.
`message`	Isi teks pesan (kosong untuk media tanpa caption).

{ "event": "incoming", "device": "dev-7c1e2a", "from": "[email protected]", "id": "3EB0…", "message": "halo" }

Perilaku: timeout 8 detik, tanpa retry — pastikan endpoint Anda cepat & selalu balas HTTP 2xx. Selama webhook terisi, autoreply nonaktif. Keamanan: gunakan path URL yang sulit ditebak (mis. /webhook/<kata-rahasia>) karena payload tidak ditandatangani.

6. Autoreply

Diatur dari dashboard (bukan API): balasan default untuk semua pesan, dan balasan kata kunci (pesan mengandung kata kunci, tidak peka huruf besar/kecil). Variabel {nama} (nama profil pengirim) dan {nomor} didukung. Batas anti-flood: maks 1 balasan per pengirim per menit. Webhook yang terisi mengambil alih — autoreply berhenti bekerja.

7. Kode error

HTTP	Code	Arti	Tindakan
`401`	`TOKEN_INVALID`	Token device tidak dikenal.	Periksa token di dashboard; regenerasi bila bocor.
`401`	`ACCOUNT_TOKEN_INVALID`	Token akun tidak dikenal (khusus /get-devices).	Gunakan token akun dari dashboard, bukan token device.
`400`	`VALIDATION_ERROR`	Parameter wajib kosong / target tidak valid.	Isi target & pesan; format nomor 08xx / 62xx / @g.us.
`403`	`PLAN_INACTIVE`	Akun nonaktif atau paket kedaluwarsa.	Perpanjang paket.
`403`	`MEDIA_NOT_ALLOWED`	Paket tidak termasuk kirim media.	Naik paket berkmedia atau kirim teks saja.
`403`	`QUOTA_EXCEEDED`	Kuota bulanan habis (termasuk antrean berjalan).	Tunggu reset bulanan atau naik paket.
`429`	`RATE_LIMITED`	Lebih dari 60 permintaan/menit per token.	Kurangi frekuensi; antrekan di sisi klien.
`405`	`METHOD_NOT_ALLOWED`	Metode HTTP salah untuk endpoint ini.	Ikuti metode pada referensi endpoint.
`200*`	`DEVICE_OFFLINE`	Device belum terhubung ke WhatsApp.	Hubungkan device (scan QR / pairing) lalu ulangi.
`200*`	`UPSTREAM_ERROR`	Gagal membaca data dari sesi WhatsApp.	Ulangi beberapa saat lagi; cek status device.
`404`	`NOT_FOUND`	Path tidak ada.	Periksa URL & base URL.
`500`	`SERVER_ERROR`	Kesalahan internal.	Ulangi; sertakan request_id bila melapor.

* DEVICE_OFFLINE & UPSTREAM_ERROR dikembalikan dengan HTTP 200 dan status:false karena keduanya adalah status domain (device), bukan kesalahan permintaan.

8. Batas & perilaku pengiriman

Jeda anti-spam	Antrean global dikirim satu per satu dengan jeda 3–8 detik acak antar pesan (pesan mengandung "OTP": ±2,5 detik, diprioritaskan). Ini menekan risiko pembatasan nomor oleh WhatsApp.
Percobaan ulang	Kegagalan kirim diulang hingga 5 kali sebelum berstatus `failed`.
Rate limit API	60 permintaan/menit per token untuk /send, /validate, /fetch-groups.
Kuota	Dihitung per pesan terkirim sesuai paket; reset otomatis tiap awal bulan. Cek sisa lewat `GET /device`.
Format nomor	`08xx` otomatis dinormalisasi ke `62xx`. Nomor di luar pola valid ditolak (`rejected`).
Risiko nomor	Gateway tidak resmi: broadcast agresif ke nomor asing berisiko dibatasi WhatsApp. Gunakan nomor khusus.

9. OpenAPI & riwayat versi

Spesifikasi mesin-terbaca (OpenAPI 3.0): GET /openapi.json — impor ke Postman/Insomnia/Swagger untuk eksplorasi & generate client.

Versi	Perubahan
`2.1`	Kode error stabil + request_id, rate limit, CORS, GET /message/:id, OpenAPI, dokumentasi lengkap.
`2.0`	Broadcast, template, kontak, autoreply, schedule/delay, kirim lokasi, /fetch-groups, /get-devices + token akun, desain web baru.
`1.0`	Rilis awal: /send, /validate, /device, multi-device, kuota paket, webhook.