# VexaHost WA Gateway - Panduan Integrasi AI Agent & Developer

> Spesifikasi teknis resmi VexaHost WA Gateway (https://wa.vexahostcloud.my.id) untuk AI Coding Assistants dan pengembang sistem.

---

## 1. Ikhtisar & Arsitektur Gateway

- **Base URL:** `https://wa.vexahostcloud.my.id/api/v1`
- **Protokol:** REST API murni berbasis `application/json`
- **Header Autentikasi:** `X-Api-Key: <API_KEY_ANDA>`
- **Endpoint Status:** `GET https://wa.vexahostcloud.my.id/status.json`
- **Dokumentasi Web:** https://wa.vexahostcloud.my.id/docs

---

## 2. Konfigurasi Variabel Lingkungan (.env)

Simpan kredensial gateway di berkas `.env` backend Anda:

```env
WA_GATEWAY_URL=https://wa.vexahostcloud.my.id
WA_GATEWAY_KEY=vwa_live_xxxxxxxxxxxxxxxx
```

---

## 3. Spesifikasi Endpoint REST API

### A. Kirim Pesan Teks
- **Method:** `POST /api/v1/messages/text`
- **Header:**
  - `Content-Type: application/json`
  - `X-Api-Key: vwa_live_xxxxxxxxxxxxxxxx`
- **Payload JSON:**
```json
{
  "to": "081234567890",
  "message": "Halo! Pesan transaksional dari sistem."
}
```
- **Format Respon Sukses (200 OK):**
```json
{
  "success": true,
  "data": {
    "id": "msg_1029",
    "status": "queued"
  }
}
```

### B. Kirim Dokumen & Media (PDF, Gambar, dsb)
- **Method:** `POST /api/v1/messages/media`
- **Header:** `Content-Type: multipart/form-data`, `X-Api-Key: vwa_live_xxxxxxxxxxxxxxxx`
- **Parameter Form:**
  - `to`: Nomor tujuan (format 08... atau 62...)
  - `caption`: Teks pesan pendamping (opsional)
  - `type`: `document` | `image` | `audio` | `video`
  - `file`: Berkas fisik yang dikirim

### C. Pengiriman Massal (Bulk Messages)
- **Method:** `POST /api/v1/messages/bulk`
- **Header:** `Content-Type: application/json`, `X-Api-Key: vwa_live_xxxxxxxxxxxxxxxx`
- **Catatan:** Server otomatis mengelola jeda dan antrean anti-blokir WhatsApp.

---

## 4. Instruksi & Prompt untuk AI Coding Assistant

### Claude Code (Anthropic CLI)
- **Target Berkas:** `CLAUDE.md`
- **Deskripsi:** Agent CLI otonom dari Anthropic yang mengeksekusi perintah terminal, merawat repositori, dan membaca instruksi dari berkas CLAUDE.md.

```text
Tambahkan integrasi WhatsApp Gateway ke project ini menggunakan REST API VexaHost WA (https://wa.vexahostcloud.my.id).

Spesifikasi integrasi:
- Base URL: https://wa.vexahostcloud.my.id/api/v1
- Endpoint kirim teks: POST /messages/text
- Header:
    X-Api-Key: env('VEXAHOST_WA_KEY')
    Content-Type: application/json
- Payload JSON:
    {
      "to": "081234567890",
      "message": "Halo! Pesan transaksional dari sistem."
    }
- Format respon sukses:
    { "success": true, "data": { "id": "msg_1029", "status": "queued" } }

Tolong buatkan helper service yang modular dengan validasi nomor tujuan dan error handling yang aman. Simpan petunjuk ini di berkas CLAUDE.md.
```

### Cursor (AI Code Editor)
- **Target Berkas:** `.cursorrules`
- **Deskripsi:** Editor AI mutakhir dengan fitur Composer. Aturan .cursorrules memastikan AI selalu menerapkan best practice integrasi WhatsApp.

```text
# Aturan VexaHost WA Gateway untuk .cursorrules

Ketika membuat fitur pengiriman pesan, notifikasi, atau verifikasi OTP WhatsApp:
1. Panggil endpoint REST API: POST https://wa.vexahostcloud.my.id/api/v1/messages/text
2. Autentikasi: sertakan header 'X-Api-Key' dari variabel lingkungan VEXAHOST_WA_KEY.
3. Payload JSON:
   {
     "to": "08xxxxxxxxxx",
     "message": "Isi pesan WhatsApp"
   }
4. Jangan pernah mengekspos API key di client-side / frontend.
5. Tangani respon galat 401 (kunci salah) dan 422 (data tidak valid) dengan elegan.
```

### Hermes Agent (Nous Research Agent)
- **Target Berkas:** `SKILL.md`
- **Deskripsi:** Framework autonomous AI agent dari Nous Research dengan memori persisten lintas sesi dan ekstensibilitas berbasis open standard SKILL.md.

```text
Definisikan skill baru untuk Hermes Agent di folder `skills/vexahost-wa/SKILL.md`:

```yaml
name: vexahost-wa-gateway
description: Kirim pesan WhatsApp notifikasi dan dokumen via VexaHost WA Gateway API.
```

Instruksi teknis untuk agent:
- Base URL: https://wa.vexahostcloud.my.id/api/v1
- Method: POST /messages/text
- Headers:
    Content-Type: application/json
    X-Api-Key: ${VEXAHOST_WA_KEY}
- Parameter fungsi `send_whatsapp(to, message)`:
    `to`: nomor WhatsApp tujuan (format 08 atau 62)
    `message`: teks pesan WhatsApp yang dikirim
- Agent harus mengecek apakah API key tersedia sebelum memanggil HTTP POST.
- Kembalikan ID pesan ('id') dan status ('queued') saat pengiriman sukses.
```

### OpenClaw (Autonomous WhatsApp Employee)
- **Target Berkas:** `openclaw.json`
- **Deskripsi:** Autonomous personal AI employee & coding agent open-source (Peter Steinberger). Mengotomatiskan pesan WhatsApp langsung melalui ReAct loop & MCP.

```text
Konfigurasikan OpenClaw (Clawdbot) dengan tool pengiriman WhatsApp resmi VexaHost WA:

1. Daftarkan tool 'send_whatsapp' di manifest tool OpenClaw:
   - Description: Mengirim notifikasi atau balasan WhatsApp ke pengguna.
   - Endpoint: POST https://wa.vexahostcloud.my.id/api/v1/messages/text
   - Header: X-Api-Key: ${env.VEXAHOST_WA_KEY}
   - Body: { "to": "<recipient_phone>", "message": "<message_text>" }
2. Standarisasi format nomor: normalisasi awalan 08 menjadi 628 secara otomatis.
3. Bila agent mendeteksi perintah pengiriman pesan atau alert sistem, jalankan tool ini dan laporkan queue ID yang diterima.
```

### Antigravity (Google DeepMind Agentic Studio)
- **Target Berkas:** `antigravity.json`
- **Deskripsi:** AI coding assistant tingkat lanjut dengan dukungan subagents, declarative rules, dan eksekusi background task mandiri.

```text
Konfigurasikan integrasi WhatsApp otomatis untuk workspace ini menggunakan VexaHost WA Gateway API:
- Base URL: https://wa.vexahostcloud.my.id/api/v1
- Endpoint: POST /messages/text
- Header: X-Api-Key: [API_KEY_ANDA], Content-Type: application/json
- Body: { "to": "08xxxxxxxxxx", "message": "Pesan otomatis sistem" }
- Dokumentasi API lengkap: https://wa.vexahostcloud.my.id/docs
- Pastikan fungsi kirim mengembalikan status antrean pesan tanpa menghentikan thread utama aplikasi.
```

### OpenCode (Open-Source AI)
- **Target Berkas:** `instructions.md`
- **Deskripsi:** Perangkat AI coding open-source berbasis terminal yang ringan dan cepat, siap membaca instruksi proyek langsung dari repositori.

```text
Integrasikan pengiriman pesan WhatsApp via VexaHost WA Gateway.
URL: https://wa.vexahostcloud.my.id/api/v1/messages/text
Method: POST
Headers:
  X-Api-Key: os.getenv('WA_KEY')
  Content-Type: application/json
Body:
  {
    "to": "081234567890",
    "message": "Pesan verifikasi sistem"
  }
Buatkan modul client HTTP yang bersih dan siap diuji.
```

### OpenAI Codex (Coding Agent)
- **Target Berkas:** `System Prompt`
- **Deskripsi:** Model bahasa penalaran kode dari OpenAI untuk scaffolding otomatis, pembuatan unit test, dan fungsi API helper.

```text
Write a clean and robust service module to send WhatsApp messages using VexaHost WA Gateway.
API URL: https://wa.vexahostcloud.my.id/api/v1/messages/text
Method: POST
Headers:
  X-Api-Key: process.env.WA_API_KEY
  Content-Type: application/json
Body:
  { "to": recipient_phone, "message": text_message }
Requirements:
- Validate phone number input (supports 08... or 628...)
- Parse JSON response and log queue message ID
- Add exponential retry on 5xx server errors
```

### Windsurf (Cascade Flow)
- **Target Berkas:** `.windsurfrules`
- **Deskripsi:** IDE Agentic dari Codeium dengan Cascade Flow yang memahami seluruh konteks codebase secara mendalam.

```text
Integrasikan VexaHost WA Gateway API ke dalam alur aplikasi:
- Endpoint: POST https://wa.vexahostcloud.my.id/api/v1/messages/text
- Header: X-Api-Key: env('WA_API_KEY')
- Request Body: { "to": "081234567890", "message": "Notifikasi pesanan siap dikirim" }
- Tangani status response: 'queued' menandakan pesan telah masuk antrean pengiriman server.
```

### Cline / Roo Code (Autonomous Agent)
- **Target Berkas:** `.clinerules`
- **Deskripsi:** Extension VS Code otonom yang dapat membuat file, menjalankan command terminal, dan mengintegrasikan API dengan panduan .clinerules.

```text
# Panduan VexaHost WA Gateway untuk .clinerules
- Base URL: https://wa.vexahostcloud.my.id/api/v1
- Endpoint Kirim Pesan: POST /messages/text
- Headers:
    Content-Type: application/json
    X-Api-Key: ${WA_GATEWAY_KEY}
- Buatkan service class modular dengan error handling yang aman tanpa menghentikan flow aplikasi saat network failure.
```

### GitHub Copilot (Copilot Workspace)
- **Target Berkas:** `copilot-instructions.md`
- **Deskripsi:** Asisten AI dari GitHub. File instruksi khusus memastikan Copilot selalu mematuhi arsitektur REST API VexaHost WA Gateway.

```text
# GitHub Copilot Instructions for WhatsApp Gateway
When implementing WhatsApp notifications, OTP, or messaging:
- Use VexaHost WA Gateway REST API: POST https://wa.vexahostcloud.my.id/api/v1/messages/text
- Always read API key from environment variable `WA_GATEWAY_KEY` (Header: `X-Api-Key`)
- Validate phone numbers to support standard Indonesian formats (08... and 62...)
- Avoid throwing fatal exceptions on notification delivery failure.
```

---

## 5. Standar Penanganan Galat (Error Handling)

- **401 Unauthorized:** Kunci API belum diisi atau salah. Periksa header `X-Api-Key`.
- **422 Unprocessable Entity:** Format nomor tujuan tidak valid atau payload tidak lengkap.
- **503 Service Unavailable:** Sesi WhatsApp sedang reconnect. Tangani dengan retry aman.