📘 Dokumentasi Resmi Hikuy REST API v1.2

Dokumentasi Integrasi Hikuy WhatsApp API

Dirancang untuk kemudahan integrasi developer: mendukung endpoint standar /api/send, /send, maupun /api/v1/messages. Setiap nomor/device memiliki token API tersendiri, mendukung kirim gambar/PDF dengan custom filename, grup (@g.us), mentions, priority instan, serta idempotency_key.

🚀 Daftar & Uji Coba Gratis 🟢 Status Server Live

Base URL & Autentikasi

https://hikuy.com

Header: Authorization: {DEVICE_API_KEY} (tanpa atau dengan kata Bearer) atau x-hikuy-key: {DEVICE_API_KEY}.

Multi-Device Token (1 Paket 1 Nomor)

Satu akun dapat memiliki banyak nomor WhatsApp (misal: Utama, MJ Trans, Internal) dengan membeli paket per nomor. Setiap device memiliki API Key sendiri (hikuy_dev_...) dan mendukung rotasi key 24 jam tanpa downtime.

Ketentuan Watermark Paket Gratis vs Berbayar

• Paket Uji Coba (Free): Otomatis menambahkan baris \n\n_Sent via Hikuy_ di bagian bawah pesan.
• Paket Mini, Standar, & Bisnis: 100% Tanpa Watermark (teks dan tautan dikirim murni).

POST /api/send (atau /send dan /api/v1/messages)

✓ REST API v1.2

Parameter	Wajib	Tipe	Keterangan
target (atau to)	Ya	string	Nomor tujuan (`0812xxx`, `62812xxx`), multi-nomor dipisah koma (maks 50 nomor per request), atau ID Grup (`[email protected]`).
message (atau caption)	Kondisional	string	Isi pesan teks atau caption untuk gambar/dokumen PDF (maks 4.096 karakter). Mendukung Spintax `{Halo\|Hai}`.
url (atau media_url)	Opsional	string (URL)	URL publik gambar (JPG/PNG/WEBP) atau dokumen (PDF/DOCX/XLSX/CSV/ZIP, maks 15 MB). Otomatis mendeteksi gambar vs dokumen.
filename	Opsional	string	Nama file saat diterima di WhatsApp (misal: `INV-2026-0081.pdf` atau `PO-Balioh.pdf`).
mentions	Opsional	string / array	Menandai anggota di dalam grup. Contoh: `"62812345678,62898765432"` atau array `["62812345678"]`.
delay / priority	Opsional	int / bool	Isi `delay: 0` atau `priority: true` untuk kirim instan tanpa menunggu jeda antrean broadcast (cocok untuk OTP & alert).
schedule (scheduled_at)	Opsional	int / datetime	Unix timestamp atau format `YYYY-MM-DD HH:mm:ss` untuk pengiriman terjadwal.
idempotency_key	Opsional	string	Kirimkan ID unik transaksi dari bisnis Anda (misal `inv-9021`) via body atau header `X-Idempotency-Key` agar saat retry tidak terkirim dua kali.

Maksimal Ukuran Media

15 MB (Kirim) / 5 MB (Masuk)

Panjang Teks / Caption

Maks. 4.096 Karakter

Rate Limit API

60 Request / Menit

Target per Request

Maks. 50 Nomor

Daftar Kode Error HTTP & Respons Gagal

Penting untuk menentukan kapan aplikasi Anda harus melakukan fallback ke penyedia cadangan:

HTTP Status	Kode `reason`	Penyebab	Rekomendasi Penanganan
400 Bad Request	device_disconnected	Sesi WhatsApp pada device sedang terputus / belum scan QR.	Aman untuk Fallback (pesan belum masuk antrean).
401 Unauthorized	invalid token	Header `Authorization` kosong atau API Key salah.	Aman untuk Fallback & periksa token di `.env`.
402 Payment Required	insufficient quota or no active subscription	Kuota pesan bulanan habis atau masa aktif paket berakhir.	Aman untuk Fallback & perpanjang paket.
403 Forbidden	IP x.x.x.x is not whitelisted	IP server pemanggil tidak terdaftar di IP Whitelist device.	Tambahkan IP server di pengaturan device.
422 Unprocessable	target / to is required	Parameter wajib (`target` atau `message`/`url`) kosong.	Perbaiki payload request (jangan di-retry).
429 Too Many Requests	Too Many Attempts.	Melebihi batas 60 request HTTP per menit.	Tunggu beberapa detik lalu ulangi dengan `idempotency_key` yang sama.

Contoh Respons 400 Device Disconnected / 402 Quota Habis:

{
  "status": false,
  "success": false,
  "reason": "device_disconnected",
  "device_status": "disconnected",
  "message": "Device WhatsApp sedang tidak terhubung (disconnected)."
}

Contoh Respons 422 Validation Error & 429 Rate Limit:

// 422 Unprocessable Entity
{
  "status": false,
  "success": false,
  "reason": "target / to is required",
  "message": "Parameter \"target\" atau \"to\" wajib diisi."
}

Format Payload Webhook (Pesan Masuk, Status Pesan & Status Device)

Setiap device mengirimkan HTTP POST (JSON) ke webhook_url Anda dilengkapi header X-Hikuy-Signature. Penting: File media masuk (https://hikuy.com/incoming-media/...) disimpan selama 7 hari; segera unduh dan simpan ke storage internal Anda saat webhook diterima.

1. Webhook Pesan Masuk (message.incoming):

{
  "event": "message.incoming",
  "device": "6281122334455",
  "device_id": 2,
  "sender": "[email protected]",
  "name": "Budi Santoso",
  "message": "Berikut bukti transfernya",
  "member": "6281299887766",
  "url": "https://hikuy.com/incoming-media/wa_20261104_a1b2c3.jpg",
  "filename": "wa_3EB0192.jpg",
  "extension": "jpg",
  "location": "-8.650000,115.216667",
  "timestamp": 1762246800
}

2. Webhook Status Pesan (message.status):

{
  "event": "message.status",
  "id": 1042,
  "message_id": 1042,
  "wa_message_id": "BAE59182736192",
  "device": "6281122334455",
  "device_id": 2,
  "target": "6281299887766",
  "status": "read",
  "state": "read",
  "reason": null,
  "timestamp": 1762246815
}

3. Webhook Status Device (session.status):

{
  "event": "session.status",
  "device": "6281122334455",
  "device_id": 2,
  "device_name": "WA Internal Balioh",
  "order_code": "HKY-20261104-9A1B",
  "status": "disconnected",
  "phone_number": null,
  "timestamp": 1762247500
}

Verifikasi Signature Keamanan di Laravel (Aman untuk php artisan config:cache):

// Gunakan config('services.hikuy.webhook_secret'), jangan memanggil env() di luar file config/*.php
$signature = (string) $request->header('X-Hikuy-Signature');
$secret    = (string) config('services.hikuy.webhook_secret');
$expected  = hash_hmac('sha256', $request->getContent(), $secret);

abort_unless(hash_equals($expected, $signature), 403, 'Invalid Hikuy Webhook Signature');