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:

[
  {
    "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):

{
  "id": "my-account",
  "type": "whatsmeow",
  "phone_number": "+1234567890",
  "session_path": "./sessions/my-account",
  "show_qr": true,
  "disabled": false
}

Request Body (Business API):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "id": "my-account"
}

Response:

{
  "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:

{
  "id": "my-account"
}

Response:

{
  "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:

{
  "id": "my-account"
}

Response:

{
  "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:

{
  "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:

curl -u username:password http://localhost:8080/api/accounts

Add account:

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:

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:

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

Enable account:

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

Remove account:

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:

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:

{
  "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)