TA/web_JMW/WHATSAPP_API_DOCUMENTATION.md

# WhatsApp Chat API Documentation

## Daftar API Endpoints

### 1. **Dapatkan Link WhatsApp Penjual**
**Endpoint:** `GET /api/chat/whatsapp/{username}/{categoryId?}`

**Deskripsi:** Mendapatkan link WhatsApp untuk menghubungi penjual

**Parameter:**
- `username` (required) - Username penjual
- `categoryId` (optional) - ID mobil/kategori yang diminati

**Response Sukses (200):**
```json
{
    "success": true,
    "message": "Link WhatsApp berhasil dibuat",
    "data": {
        "seller_username": "john_seller",
        "seller_name": "john_seller",
        "phone_number": "+6281234567890",
        "whatsapp_link": "https://wa.me/6281234567890?text=Halo...",
        "car_name": "Toyota Avanza 2015"
    }
}
```

**Response Error (404):**
```json
{
    "success": false,
    "message": "Penjual tidak ditemukan"
}
```

**Response Error (422):**
```json
{
    "success": false,
    "message": "Nomor telepon penjual tidak tersedia"
}
```

**Contoh Request:**
```
GET http://localhost:8000/api/chat/whatsapp/john_seller/5
```

---

### 2. **Dapatkan Daftar Semua Penjual**
**Endpoint:** `GET /api/chat/sellers`

**Deskripsi:** Mendapatkan list semua penjual dengan informasi kontak

**Response Sukses (200):**
```json
{
    "success": true,
    "message": "Daftar penjual berhasil diambil",
    "data": [
        {
            "username": "john_seller",
            "email": "john@example.com",
            "phone_number": "+6281234567890"
        },
        {
            "username": "maria_seller",
            "email": "maria@example.com",
            "phone_number": "+6282345678901"
        }
    ]
}
```

**Contoh Request:**
```
GET http://localhost:8000/api/chat/sellers
```

---

### 3. **Redirect Langsung ke WhatsApp**
**Endpoint:** `GET /contact/whatsapp/{username}/{categoryId?}`

**Deskripsi:** Redirect langsung ke WhatsApp Web/App dengan pesan otomatis

**Parameter:**
- `username` (required) - Username penjual
- `categoryId` (optional) - ID mobil/kategori

**Behavior:**
- Secara otomatis membuka WhatsApp Web atau aplikasi WhatsApp yang terinstall
- Pesan otomatis dikirim ke chat window

**Contoh Request:**
```
GET http://localhost:8000/api/contact/whatsapp/john_seller/5
```

---

## Cara Menggunakan

### Option 1: Dari Frontend (HTML Button)
```html
<!-- Button untuk membuka WhatsApp -->
<a href="/api/contact/whatsapp/john_seller/5" class="btn btn-primary">
    Hubungi Penjual via WhatsApp
</a>
```

### Option 2: Dari Frontend (JavaScript)
```javascript
// Dapatkan link WhatsApp dari API
fetch('/api/chat/whatsapp/john_seller/5')
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            // Buka link di tab baru
            window.open(data.data.whatsapp_link, '_blank');
        } else {
            alert(data.message);
        }
    });
```

### Option 3: Mobile App
```javascript
// Untuk membuka WhatsApp App di mobile
const whatsappLink = "whatsapp://send?phone=6281234567890&text=Halo";
window.location.href = whatsappLink;
```

---

## Setup & Migration

### 1. Jalankan Migration untuk menambah field phone_number
```bash
php artisan migrate
```

Ini akan menambahkan kolom `phone_number` ke tabel `user`.

### 2. Update data penjual dengan nomor telepon
```bash
php artisan tinker
```

```php
$user = User::find('john_seller');
$user->update(['phone_number' => '+6281234567890']);
```

Atau melalui database secara langsung:
```sql
UPDATE user SET phone_number = '+6281234567890' WHERE username = 'john_seller';
```

---

## Format Nomor Telepon

API secara otomatis memformat nomor telepon. Nomor dapat diterima dalam format:
- ✅ `081234567890` (Indonesian mobile)
- ✅ `08-1234-567890` (dengan separator)
- ✅ `+6281234567890` (international)
- ✅ `6281234567890` (country code tanpa +)

Semua format akan dikonversi menjadi: `6281234567890` untuk link WhatsApp.

---

## Pesan Otomatis

Pesan default yang dikirim:
```
Halo, saya tertarik dengan kendaraan bekas - [Nama Mobil]. Apakah masih tersedia?
```

Contoh pesan dengan car_name:
```
Halo, saya tertarik dengan kendaraan bekas - Toyota Avanza 2015. Apakah masih tersedia?
```

---

## Integrasi pada Car Detail Page

Tambahkan tombol "Hubungi Penjual" pada halaman detail mobil:

```blade
<!-- resources/views/user/car-detail.blade.php -->
<button onclick="contactSeller('{{ $seller->username }}', '{{ $car->id }}')">
    Hubungi Penjual via WhatsApp
</button>

<script>
function contactSeller(username, categoryId) {
    window.location.href = `/api/contact/whatsapp/${username}/${categoryId}`;
}
</script>
```

---

## Error Handling

**Error 404 - Penjual tidak ditemukan:**
- Pastikan username penjual correct/exists di database

**Error 422 - Nomor telepon tidak tersedia:**
- Update field `phone_number` untuk user tersebut
- Pastikan nomor telepon dalam format yang valid

**Error 500 - Server error:**
- Cek log file di `storage/logs/`
- Pastikan semua field exists di model

---

## Catatan Penting

1. **Nomor Telepon Wajib:**
   - User/Penjual harus memiliki nomor telepon di field `phone_number`

2. **Role Seller:**
   - Untuk endpoint `/api/chat/sellers`, hanya users dengan role 'seller' yang ditampilkan

3. **WhatsApp Web:**
   - Pengguna harus sudah login di WhatsApp Web
   - Atau memiliki aplikasi WhatsApp yang terinstall

4. **Character Encoding:**
   - Pesan otomatis di-encode dengan `urlencode()` untuk mendukung karakter khusus

---

## Troubleshooting

### Link WhatsApp tidak buka
- Pastikan WhatsApp Web sudah login atau aplikasi terinstall
- Coba akses link langsung: `https://wa.me/6281234567890`

### Nomor telepon tidak valid
- Check format nomor di database
- Gunakan format: `+62xxxxxxxxxx` atau `08xxxxxxxxxx`

### Pesan tidak muncul
- Pastikan browser memperbolehkan popup/redirect
- Coba buka di incognito mode

---

## Contact untuk Support
Jika ada pertanyaan atau issue, hubungi team development.