whatshooked/ACCOUNT_MANAGEMENT.md

# Account Management API

This document describes the API endpoints for managing WhatsApp accounts in WhatsHooked.

## Authentication

All account management endpoints require authentication using one of the following methods:

- **API Key**: `X-API-Key: your-api-key-here`
- **Basic Auth**: `Authorization: Basic <base64(username:password)>`

## Endpoints

### 1. List All Accounts

Get a list of all configured WhatsApp accounts.

**Endpoint:** `GET /api/accounts`

**Response:**
```json
[
  {
    "id": "business",
    "type": "business-api",
    "phone_number": "+27663602295",
    "disabled": false,
    "business_api": {
      "phone_number_id": "889966060876308",
      "access_token": "...",
      "business_account_id": "1602055757491196",
      "api_version": "v21.0",
      "verify_token": "..."
    }
  }
]
```

---

### 2. Add Account

Add a new WhatsApp account to the system.

**Endpoint:** `POST /api/accounts/add`

**Request Body (WhatsApp Web/WhatsMe ow):**
```json
{
  "id": "my-account",
  "type": "whatsmeow",
  "phone_number": "+1234567890",
  "session_path": "./sessions/my-account",
  "show_qr": true,
  "disabled": false
}
```

**Request Body (Business API):**
```json
{
  "id": "business-account",
  "type": "business-api",
  "phone_number": "+1234567890",
  "disabled": false,
  "business_api": {
    "phone_number_id": "123456789",
    "access_token": "YOUR_ACCESS_TOKEN",
    "business_account_id": "987654321",
    "api_version": "v21.0",
    "verify_token": "your-verify-token"
  }
}
```

**Response:**
```json
{
  "status": "ok",
  "account_id": "my-account"
}
```

**Status Codes:**
- `201 Created` - Account added successfully
- `400 Bad Request` - Invalid request body
- `500 Internal Server Error` - Failed to connect or save config

---

### 3. Update Account

Update an existing WhatsApp account configuration.

**Endpoint:** `POST /api/accounts/update` or `PUT /api/accounts/update`

**Request Body:**
```json
{
  "id": "business-account",
  "type": "business-api",
  "phone_number": "+1234567890",
  "disabled": false,
  "business_api": {
    "phone_number_id": "123456789",
    "access_token": "NEW_ACCESS_TOKEN",
    "business_account_id": "987654321",
    "api_version": "v21.0",
    "verify_token": "new-verify-token"
  }
}
```

**Response:**
```json
{
  "status": "ok",
  "account_id": "business-account"
}
```

**Notes:**
- The `id` field is required to identify which account to update
- The `type` field cannot be changed (preserved from original)
- If the account is enabled, it will be disconnected and reconnected with new settings
- Configuration is saved to disk after successful update

**Status Codes:**
- `200 OK` - Account updated successfully
- `400 Bad Request` - Invalid request or missing ID
- `404 Not Found` - Account not found
- `500 Internal Server Error` - Failed to reconnect or save config

---

### 4. Disable Account

Disable a WhatsApp account (disconnect and prevent auto-connect on restart).

**Endpoint:** `POST /api/accounts/disable`

**Request Body:**
```json
{
  "id": "my-account"
}
```

**Response:**
```json
{
  "status": "ok",
  "account_id": "my-account"
}
```

**Behavior:**
- Disconnects the account immediately
- Sets `disabled: true` in config
- Account will not auto-connect on server restart
- Account remains in config (can be re-enabled)

**Status Codes:**
- `200 OK` - Account disabled successfully
- `400 Bad Request` - Invalid request body
- `404 Not Found` - Account not found
- `500 Internal Server Error` - Failed to save config

---

### 5. Enable Account

Enable a previously disabled WhatsApp account.

**Endpoint:** `POST /api/accounts/enable`

**Request Body:**
```json
{
  "id": "my-account"
}
```

**Response:**
```json
{
  "status": "ok",
  "account_id": "my-account"
}
```

**Behavior:**
- Sets `disabled: false` in config
- Connects the account immediately
- Account will auto-connect on server restart
- If connection fails, account remains disabled

**Status Codes:**
- `200 OK` - Account enabled and connected successfully
- `400 Bad Request` - Invalid request body
- `404 Not Found` - Account not found
- `500 Internal Server Error` - Failed to connect or save config

---

### 6. Remove Account

Permanently remove a WhatsApp account from the system.

**Endpoint:** `POST /api/accounts/remove` or `DELETE /api/accounts/remove`

**Request Body:**
```json
{
  "id": "my-account"
}
```

**Response:**
```json
{
  "status": "ok"
}
```

**Behavior:**
- Disconnects the account
- Removes from config permanently
- Session data is NOT deleted (manual cleanup required)

**Status Codes:**
- `200 OK` - Account removed successfully
- `400 Bad Request` - Invalid request body
- `404 Not Found` - Account not found
- `500 Internal Server Error` - Failed to save config

---

## Configuration File

Account settings are stored in `config.json`:

```json
{
  "whatsapp": [
    {
      "id": "business",
      "type": "business-api",
      "phone_number": "+27663602295",
      "disabled": false,
      "business_api": {
        "phone_number_id": "889966060876308",
        "access_token": "...",
        "business_account_id": "1602055757491196",
        "api_version": "v21.0",
        "verify_token": "..."
      }
    },
    {
      "id": "personal",
      "type": "whatsmeow",
      "phone_number": "+1234567890",
      "session_path": "./sessions/personal",
      "show_qr": true,
      "disabled": true
    }
  ]
}
```

### Configuration Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique identifier for the account |
| `type` | string | Yes | Account type: `whatsmeow` or `business-api` |
| `phone_number` | string | Yes | Phone number with country code |
| `disabled` | boolean | No | If `true`, account won't connect (default: `false`) |
| `session_path` | string | No | Session storage path (whatsmeow only) |
| `show_qr` | boolean | No | Display QR code in logs (whatsmeow only) |
| `business_api` | object | Conditional | Required for `business-api` type |

### Business API Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `phone_number_id` | string | Yes | WhatsApp Business phone number ID |
| `access_token` | string | Yes | Meta Graph API access token |
| `business_account_id` | string | No | Business account ID |
| `api_version` | string | No | API version (default: `v21.0`) |
| `verify_token` | string | No | Webhook verification token |

---

## Usage Examples

### cURL Examples

**List accounts:**
```bash
curl -u username:password http://localhost:8080/api/accounts
```

**Add account:**
```bash
curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "id": "new-account",
    "type": "whatsmeow",
    "phone_number": "+1234567890",
    "session_path": "./sessions/new-account",
    "show_qr": true
  }' \
  http://localhost:8080/api/accounts/add
```

**Update account:**
```bash
curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "id": "business",
    "type": "business-api",
    "phone_number": "+27663602295",
    "business_api": {
      "phone_number_id": "889966060876308",
      "access_token": "NEW_TOKEN_HERE",
      "api_version": "v21.0"
    }
  }' \
  http://localhost:8080/api/accounts/update
```

**Disable account:**
```bash
curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": "my-account"}' \
  http://localhost:8080/api/accounts/disable
```

**Enable account:**
```bash
curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": "my-account"}' \
  http://localhost:8080/api/accounts/enable
```

**Remove account:**
```bash
curl -u username:password \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": "my-account"}' \
  http://localhost:8080/api/accounts/remove
```

---

## Server Logs

When managing accounts, you'll see these log messages:

```log
INFO Account disabled account_id=business
INFO Config saved after disabling account account_id=business

INFO Account enabled and connected account_id=business
INFO Config saved after enabling account account_id=business

INFO Account configuration updated account_id=business
INFO Account reconnected with new settings account_id=business

INFO Skipping disabled account account_id=business
```

---

## Best Practices

1. **Disable vs Remove**:
   - Use **disable** for temporary disconnection (maintenance, testing)
   - Use **remove** for permanent deletion

2. **Update Process**:
   - Always provide complete configuration when updating
   - Account will be reconnected automatically if enabled

3. **Session Management**:
   - WhatsMe ow sessions are stored in `session_path`
   - Removing an account doesn't delete session files
   - Clean up manually if needed

4. **Server Restart**:
   - Only enabled accounts (`disabled: false`) connect on startup
   - Disabled accounts remain in config but stay disconnected

5. **Configuration Backup**:
   - Config is automatically saved after each change
   - Keep backups before making bulk changes
   - Test changes with one account first

---

## Error Handling

All endpoints return proper HTTP status codes and JSON error messages:

```json
{
  "error": "Account not found"
}
```

Or plain text for simple errors:
```
Account ID required in path
```

Common error scenarios:
- Account already exists (when adding)
- Account not found (when updating/removing)
- Connection failed (when enabling)
- Configuration save failed (any operation)