### Chatery WhatsApp Quick Start Guide

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

A quick start guide for the Chatery WhatsApp project, showing essential commands to start the server, create a session, get a QR code, and send a message using cURL.

```bash
# Start the server
npm start

# Create a session
curl -X POST http://localhost:3000/api/whatsapp/sessions/mysession/connect \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json"

# Get QR Code
# http://localhost:3000/api/whatsapp/sessions/mysession/qr/image (requires API key)

# Send a message
curl -X POST http://localhost:3000/api/whatsapp/chats/send-text \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "mysession", "chatId": "628123456789", "message": "Hello!"}'
```

--------------------------------

### Standard Installation of Chatery WhatsApp API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Instructions for setting up the Chatery project locally using Git and npm. This process involves cloning the repository, installing dependencies, configuring the environment, and starting the server.

```bash
git clone https://github.com/farinchan/chatery_whatsapp.git
cd chatery_whatsapp
npm install
cp .env.example .env
npm start
```

--------------------------------

### Docker Installation of Chatery WhatsApp API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Instructions for deploying the Chatery project using Docker Compose. This method is recommended for containerized environments to ensure consistent configuration and easy management.

```bash
git clone https://github.com/farinchan/chatery_whatsapp.git
cd chatery_whatsapp
cp .env.example .env
docker-compose up -d
```

--------------------------------

### API Key Authentication Setup for Chatery WhatsApp

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Demonstrates how to set up and use API key authentication for the Chatery WhatsApp API. This includes setting the API key in the .env file and including the 'X-Api-Key' header in requests.

```bash
# Enable API Key Authentication
API_KEY=your_super_secret_key_12345

# Example cURL request
curl -X GET http://localhost:3000/api/whatsapp/sessions \
  -H "X-Api-Key: your_super_secret_key_12345"
```

```bash
# Disable API Key Authentication
API_KEY=
# or
API_KEY=your_api_key_here
```

--------------------------------

### Get QR Code for Session

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves the QR code needed to connect your WhatsApp account to the session.

```APIDOC
## GET /api/whatsapp/sessions/{sessionId}/qr/image

### Description
Retrieves the QR code image for a given session. This QR code is used to link your WhatsApp account.

### Method
GET

### Endpoint
`/api/whatsapp/sessions/{sessionId}/qr/image`

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The unique identifier for the session.

### Request Example
Access this URL in your browser or use curl:
```
http://localhost:3000/api/whatsapp/sessions/mysession/qr/image
```

Or using curl with authentication:
```bash
curl -X GET http://localhost:3000/api/whatsapp/sessions/mysession/qr/image \
  -H "X-Api-Key: your_api_key"
```

### Response
#### Success Response (200)
- **Image** (image/png) - The QR code image.

#### Response Example
(Returns a PNG image stream)
```

--------------------------------

### Document Ready Event Listener and Initialization

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Sets up event listeners for when the DOM is fully loaded. It checks authentication, connects to the WebSocket, loads sessions, and starts periodic updates for WebSocket statistics.

```JavaScript
document.addEventListener('DOMContentLoaded', async () => {
  if (!checkAuth()) {
    const loggedIn = await promptLogin();
    if (!loggedIn) return;
  }
  connectWebSocket();
  loadSessions();
  loadWsStats();
  updateRequestBody();
  setInterval(() => {
    loadSessions();
    loadWsStats();
  }, 30000);
});
```

--------------------------------

### Get Chats Overview (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Fetches an overview of chats, allowing filtering by type and pagination. Requires a session ID and optional limit/offset parameters.

```http
POST /chats/overview
```

--------------------------------

### Chatery WhatsApp Environment Configuration (.env file)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Example of the .env file used to configure the Chatery WhatsApp application. It includes settings for the server port, CORS origin, dashboard authentication credentials, and API key for authentication.

```env
PORT=3000
CORS_ORIGIN=*

DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=securepassword123

API_KEY=your_secret_api_key_here
```

--------------------------------

### Docker Compose Commands for Chatery WhatsApp

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Common Docker Compose commands used to manage the Chatery WhatsApp application containers. These commands allow for starting, stopping, viewing logs, restarting, and rebuilding the application's Docker images.

```bash
docker-compose up -d
docker-compose down
docker-compose logs -f
docker-compose restart
docker-compose build --no-cache
```

--------------------------------

### Get QR Code (JSON) (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves the QR code for a session in JSON format. This is typically used for initiating a new WhatsApp connection.

```http
GET /sessions/:sessionId/qr
```

--------------------------------

### Get QR Code (Image) (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves the QR code for a session as a PNG image. This image can be directly displayed or scanned by a WhatsApp client.

```http
GET /sessions/:sessionId/qr/image
```

--------------------------------

### Get All Groups (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves a list of all groups the authenticated session is part of. Returns group details such as ID, subject, participant count, and creation timestamp.

```http
POST /groups
```

--------------------------------

### Get All Bulk Jobs (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves a list of all initiated bulk messaging jobs. This endpoint requires a session ID and returns job details including status, counts, and timestamps.

```http
POST /chats/bulk-jobs
```

--------------------------------

### Get All Groups

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve a list of all groups the user is a part of.

```APIDOC
## POST /api/whatsapp/groups

### Description
Get all groups you are participating in.

### Method
POST

### Endpoint
/api/whatsapp/groups

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.

### Request Example
```json
{
  "sessionId": "your_session_id"
}
```

### Response
#### Success Response (200)
- **groups** (array of objects) - An array of group objects.
  - **id** (string) - The group ID.
  - **name** (string) - The group name.

#### Response Example
```json
{
  "groups": [
    {
      "id": "123456789@g.us",
      "name": "My Group"
    }
  ]
}
```
```

--------------------------------

### Get Contacts

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve a list of contacts, with options for filtering and searching.

```APIDOC
## POST /api/whatsapp/contacts

### Description
Get a list of contacts. Allows filtering by name or number using the search parameter.

### Method
POST

### Endpoint
/api/whatsapp/contacts

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **limit** (integer) - Optional - Maximum number of contacts to return (default: 100).
- **offset** (integer) - Optional - Number of contacts to skip for pagination (default: 0).
- **search** (string) - Optional - Filter contacts by name or number.

### Request Example
```json
{
  "sessionId": "your_session_id",
  "search": "John"
}
```

### Response
#### Success Response (200)
- **contacts** (array of objects) - An array of contact objects.
  - **id** (string) - The contact's ID.
  - **name** (string) - The contact's name.
  - **pushname** (string) - The contact's push name.

#### Response Example
```json
{
  "contacts": [
    {
      "id": "628123456789@s.whatsapp.net",
      "name": "John Doe",
      "pushname": "John"
    }
  ]
}
```
```

--------------------------------

### Get Chat Info

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve detailed information about a specific chat or group.

```APIDOC
## POST /api/whatsapp/chats/info

### Description
Get detailed information about a chat or group, including participants, admins, and settings.

### Method
POST

### Endpoint
/api/whatsapp/chats/info

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **chatId** (string) - Required - The ID of the chat (e.g., '628123456789@s.whatsapp.net' or '123456789@g.us').

### Request Example
```json
{
  "sessionId": "your_session_id",
  "chatId": "123456789@g.us"
}
```

### Response
#### Success Response (200)
- **chatInfo** (object) - An object containing detailed chat information.
  - **id** (string) - The chat ID.
  - **name** (string) - The name of the chat/group.
  - **isGroup** (boolean) - True if it's a group chat.
  - **participants** (array of objects) - List of participants (if group).
  - **adminIds** (array of strings) - List of admin IDs (if group).

#### Response Example
```json
{
  "chatInfo": {
    "id": "123456789@g.us",
    "name": "Awesome Group",
    "isGroup": true,
    "participants": [
      // ... participant details ...
    ],
    "adminIds": ["628123456789@s.whatsapp.net"]
  }
}
```
```

--------------------------------

### Listen for WebSocket Events

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Demonstrates how to listen for incoming messages, QR code generation, and connection status updates.

```javascript
const socket = io('http://localhost:3000');

socket.on('connect', () => {
  console.log('Connected to WebSocket');
  socket.emit('subscribe', 'mysession');
});

socket.on('message', (data) => {
  console.log('New message:', data.message);
});

socket.on('qr', (data) => {
  console.log('Scan QR Code:', data.qrCode);
});

socket.on('connection.update', (data) => {
  console.log('Connection status:', data.status);
});
```

--------------------------------

### Get Chat Messages

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve messages from a specific chat, with support for pagination.

```APIDOC
## POST /api/whatsapp/chats/messages

### Description
Get messages from a specific chat. Supports pagination using a cursor (message ID).

### Method
POST

### Endpoint
/api/whatsapp/chats/messages

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **chatId** (string) - Required - The ID of the chat. Use '@s.whatsapp.net' for personal chats and '@g.us' for groups.
- **limit** (integer) - Optional - Maximum number of messages to return (default: 50).
- **cursor** (string) - Optional - Message ID for pagination. Use the ID of the last message received to fetch older messages.

### Request Example
```json
{
  "sessionId": "your_session_id",
  "chatId": "628123456789@s.whatsapp.net",
  "limit": 30
}
```

### Response
#### Success Response (200)
- **messages** (array of objects) - An array of message objects.
  - **id** (string) - The message ID.
  - **fromMe** (boolean) - True if the message was sent by you.
  - **text** (string) - The message content.
  - **timestamp** (integer) - Timestamp of the message.

#### Response Example
```json
{
  "messages": [
    {
      "id": "message_abc123",
      "fromMe": false,
      "text": "Hi there!",
      "timestamp": 1678886400
    }
  ]
}
```
```

--------------------------------

### Configuration (.env file)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Environment variables for configuring the Chatery WhatsApp application.

```APIDOC
## Configuration

Create a `.env` file in the root directory:

```env
PORT=3000
CORS_ORIGIN=*

# Dashboard Authentication
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=securepassword123

# API Key Authentication (optional - leave empty or 'your_api_key_here' to disable)
API_KEY=your_secret_api_key_here
```
```

--------------------------------

### Get All Groups - Chatery WhatsApp API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieves a list of all groups the user is a participant in.

```javascript
body = {
  sessionId: ''
};
helpText = '👥 Get all groups you are participating in.';
```

--------------------------------

### Initialize WebSocket Connection

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Establishes a connection to the WebSocket server and manages session subscriptions.

```javascript
import { io } from 'socket.io-client';

const socket = io('http://localhost:3000');

// Subscribe to a session
socket.emit('subscribe', 'mysession');

// Unsubscribe from a session
socket.emit('unsubscribe', 'mysession');
```

--------------------------------

### Get Profile Picture

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves the profile picture associated with a given phone number.

```http
POST /chats/profile-picture
```

```json
{
  "sessionId": "mysession",
  "phone": "628123456789"
}
```

--------------------------------

### Get All Bulk Jobs

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves a list of all bulk jobs associated with a specific session.

```APIDOC
## POST /api/whatsapp/chats/bulk-jobs

### Description
Retrieves all bulk jobs for a session.

### Method
POST

### Endpoint
/api/whatsapp/chats/bulk-jobs

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID to filter bulk jobs by.

### Request Example
```json
{
  "sessionId": "mysession"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array of objects) - A list of bulk jobs.
  - **jobId** (string) - The unique ID for the bulk job.
  - **type** (string) - The type of bulk job (e.g., "text", "image").
  - **status** (string) - The current status of the job.
  - **total** (number) - The total number of messages intended for the job.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "jobId": "bulk_1704326400000_abc123def",
      "type": "text",
      "status": "completed",
      "total": 50
    }
  ]
}
```
```

--------------------------------

### Get Invite Code

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves the current invitation code and link for a specified WhatsApp group.

```APIDOC
## POST /api/whatsapp/groups/invite-code

### Description
Retrieves the group invitation code/link.

### Method
POST

### Endpoint
/api/whatsapp/groups/invite-code

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **groupId** (string) - Required - The ID of the group to get the invite code from.

### Request Example
```json
{
  "sessionId": "mysession",
  "groupId": "123456789@g.us"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A confirmation message.
- **data** (object) - Contains the invite details.
  - **groupId** (string) - The ID of the group.
  - **inviteCode** (string) - The invitation code.
  - **inviteLink** (string) - The full invitation link.

#### Response Example
```json
{
  "success": true,
  "message": "Invite code retrieved successfully",
  "data": {
    "groupId": "123456789@g.us",
    "inviteCode": "AbCdEfGhIjKlMn",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjKlMn"
  }
}
```
```

--------------------------------

### Create or Connect WhatsApp Session

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Initializes a new WhatsApp session or reconnects an existing one. Accepts optional metadata and webhook configurations in the request body.

```bash
curl -X POST http://localhost:3000/api/whatsapp/sessions/mysession/connect \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "userId": "user123",
      "plan": "premium"
    },
    "webhooks": [
      {"url": "https://example.com/webhook", "events": ["all"]},
      {"url": "https://analytics.example.com/webhook", "events": ["message"]}
    ]
  }'
```

--------------------------------

### Get Bulk Job Status

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves the status and progress of a specific bulk messaging job.

```APIDOC
## GET /api/whatsapp/chats/bulk-status/{jobId}

### Description
Retrieves the status and progress of a bulk messaging job.

### Method
GET

### Endpoint
/api/whatsapp/chats/bulk-status/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the bulk job to retrieve status for.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the status details of the bulk job.
  - **sessionId** (string) - The session ID used for the job.
  - **type** (string) - The type of bulk job (e.g., "text", "image").
  - **status** (string) - The current status of the job (e.g., "completed", "processing", "failed").
  - **total** (number) - The total number of messages to be sent.
  - **sent** (number) - The number of messages successfully sent.
  - **failed** (number) - The number of messages that failed to send.
  - **progress** (number) - The completion percentage of the job.
  - **details** (array of objects) - Detailed status for each recipient.
    - **recipient** (string) - The recipient's phone number.
    - **status** (string) - The status for this specific recipient (e.g., "sent", "failed").
    - **messageId** (string) - The message ID if sent successfully.
    - **error** (string) - Error message if sending failed.
    - **timestamp** (string) - Timestamp of the status update.
  - **createdAt** (string) - Timestamp when the job was created.
  - **completedAt** (string) - Timestamp when the job was completed.

#### Response Example
```json
{
  "success": true,
  "data": {
    "sessionId": "mysession",
    "type": "text",
    "status": "completed",
    "total": 50,
    "sent": 48,
    "failed": 2,
    "progress": 100,
    "details": [
      {
        "recipient": "628123456789",
        "status": "sent",
        "messageId": "ABC123",
        "timestamp": "2024-01-15T10:00:00.000Z"
      },
      {
        "recipient": "628987654321",
        "status": "failed",
        "error": "Number not registered",
        "timestamp": "2024-01-15T10:00:01.000Z"
      }
    ],
    "createdAt": "2024-01-15T10:00:00.000Z",
    "completedAt": "2024-01-15T10:02:30.000Z"
  }
}
```
```

--------------------------------

### Create WhatsApp Session

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Initiates a new WhatsApp session. This is the first step to connect your WhatsApp account.

```APIDOC
## POST /api/whatsapp/sessions/{sessionId}/connect

### Description
Creates and connects a new WhatsApp session.

### Method
POST

### Endpoint
`/api/whatsapp/sessions/{sessionId}/connect`

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The unique identifier for the session.

#### Request Body
None

### Request Example
```bash
curl -X POST http://localhost:3000/api/whatsapp/sessions/mysession/connect \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the session is being created.

#### Response Example
```json
{
  "message": "Session mysession is being created"
}
```
```

--------------------------------

### Connect to WebSocket and Subscribe to Events

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Establishes a WebSocket connection to the server and subscribes to various session events for real-time notifications. Handles connection, subscription confirmation, QR code generation, connection status updates, message events, presence updates, group changes, and logout.

```javascript
import { io } from 'socket.io-client';

const socket = io('http://localhost:3000');

// Subscribe to a session
socket.on('connect', () => {
  console.log('Connected to WebSocket');
  socket.emit('subscribe', 'mysession');
});

// Handle subscription confirmation
socket.on('subscribed', (data) => {
  console.log('Subscribed:', data.message);
});

// Handle QR code generation
socket.on('qr', (data) => {
  console.log('QR Code ready:', data.qrCode);
});

// Handle connection status changes
socket.on('connection.update', (data) => {
  console.log('Connection status:', data.status);
  if (data.status === 'connected') {
    console.log(`Connected as ${data.name} (${data.phoneNumber})`);
  }
});

// Handle new incoming messages
socket.on('message', (data) => {
  console.log('New message:', data.message);
});

// Handle message sent confirmation
socket.on('message.sent', (data) => {
  console.log('Message sent:', data.message);
});

// Handle message status updates (read, delivered)
socket.on('message.update', (data) => {
  console.log('Message status update:', data.update);
});

// Handle presence updates (typing, online)
socket.on('presence.update', (data) => {
  console.log('Presence update:', data.presence);
});

// Handle group updates
socket.on('group.participants', (data) => {
  console.log('Group participants changed:', data.update);
});

// Handle logout
socket.on('logged.out', (data) => {
  console.log('Session logged out:', data.message);
});

// Unsubscribe when done
socket.emit('unsubscribe', 'mysession');
```

--------------------------------

### GET /api/whatsapp/sessions

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves a list of all active WhatsApp sessions including connection status and metadata.

```APIDOC
## GET /api/whatsapp/sessions

### Description
Retrieves information about all active WhatsApp sessions including connection status, phone number, and configured webhooks.

### Method
GET

### Endpoint
/api/whatsapp/sessions

### Parameters
#### Headers
- **X-Api-Key** (string) - Required - API authentication key

### Request Example
curl -X GET http://localhost:3000/api/whatsapp/sessions -H "X-Api-Key: your_api_key"

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **data** (array) - List of session objects

#### Response Example
{
  "success": true,
  "message": "Sessions retrieved",
  "data": [
    {
      "sessionId": "mysession",
      "status": "connected",
      "isConnected": true,
      "phoneNumber": "628123456789",
      "name": "John Doe"
    }
  ]
}
```

--------------------------------

### Load and Render Webhooks

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Fetches and displays the list of configured webhooks for a session. It handles loading states and error scenarios while rendering the webhook list dynamically.

```javascript
async function loadWebhooks(sessionId) { const container = document.getElementById('webhooksList'); container.innerHTML = '<div style="text-align: center; color: var(--text-muted); padding: 16px;"><div class="spinner"></div></div>'; try { const session = sessions.find(s => s.sessionId === sessionId); const webhooks = session?.webhooks || []; if (webhooks.length === 0) { container.innerHTML = '<div style="text-align: center; color: var(--text-muted); padding: 16px;">No webhooks configured</div>'; return; } container.innerHTML = webhooks.map((wh, index) => ` <div style="background: var(--card-bg); border-radius: 8px; padding: 12px; margin-bottom: 8px; display: flex; justify-content: space-between; align-items: flex-start;"> <div style="flex: 1; overflow: hidden;"> <div style="font-size: 13px; font-weight: 500; word-break: break-all;">${wh.url}</div> <div style="font-size: 11px; color: var(--text-muted); margin-top: 4px;"> ${wh.events && wh.events.length > 0 ? `Events: ${wh.events.join(', ')}` : 'All events'} </div> </div> <button class="btn btn-danger btn-icon" data-webhook-url="${encodeURIComponent(wh.url)}" onclick="removeWebhook(decodeURIComponent(this.dataset.webhookUrl))" title="Remove" style="margin-left: 8px;"> 🗑️ </button> </div> `).join(''); } catch (error) { container.innerHTML = '<div style="text-align: center; color: #ef4444; padding: 16px;">Error loading webhooks</div>'; console.error('Error loading webhooks:', error); } }
```

--------------------------------

### Get Group Metadata

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve detailed metadata for a specific group, including participants and admin information.

```APIDOC
## POST /api/whatsapp/groups/metadata

### Description
Get detailed group information, including participants, admins, and settings.

### Method
POST

### Endpoint
/api/whatsapp/groups/metadata

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **groupId** (string) - Required - The ID of the group.

### Request Example
```json
{
  "sessionId": "your_session_id",
  "groupId": "123456789@g.us"
}
```

### Response
#### Success Response (200)
- **groupMetadata** (object) - Object containing group metadata.
  - **id** (string) - Group ID.
  - **subject** (string) - Group subject/name.
  - **creationTime** (integer) - Timestamp of group creation.
  - **owner** (string) - ID of the group owner.
  - **participants** (array of objects) - List of participants.
  - **adminIds** (array of strings) - List of admin IDs.

#### Response Example
```json
{
  "groupMetadata": {
    "id": "123456789@g.us",
    "subject": "Project Alpha",
    "creationTime": 1670000000,
    "owner": "628123456789@s.whatsapp.net",
    "participants": [
      // ... participant details ...
    ],
    "adminIds": ["628123456789@s.whatsapp.net"]
  }
}
```
```

--------------------------------

### WebSocket Connection and Event Handling

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Establishes a WebSocket connection using Socket.IO and defines handlers for various events like connection, disconnection, QR code generation, session updates, and message reception. It subscribes to all sessions upon connection.

```JavaScript
function connectWebSocket() {
  socket = io(window.location.origin);
  socket.on('connect', () => {
    updateWsStatus(true);
    addEvent('connection', 'WebSocket connected');
    sessions.forEach(s => socket.emit('subscribe', s.sessionId));
  });
  socket.on('disconnect', () => {
    updateWsStatus(false);
    addEvent('error', 'WebSocket disconnected');
  });
  socket.on('qr', (data) => {
    addEvent('qr', `QR Code generated for ${data.sessionId}`);
    showQrCode(data.sessionId, data.qrCode);
  });
  socket.on('connection.update', (data) => {
    addEvent('connection', `${data.sessionId}: ${data.status}`);
    if (data.status === 'connected') {
      closeQrModal();
      showToast('success', `Session ${data.sessionId} connected!`);
    }
    loadSessions();
  });
  socket.on('message', (data) => {
    const from = data.message?.from || 'unknown';
    const text = data.message?.text || data.message?.caption || '[media]';
    addEvent('message', `From ${from}: ${text.substring(0, 50)}...`);
  });
  socket.on('message.sent', (data) => {
    addEvent('message', `Message sent to ${data.message?.to || 'unknown'}`);
  });
  socket.on('logged.out', (data) => {
    addEvent('error', `Session ${data.sessionId} logged out`);
    loadSessions();
  });
}
```

--------------------------------

### Docker Commands

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Common Docker commands for managing the Chatery WhatsApp application containers.

```APIDOC
## Docker Commands

| Command | Description |
|---|---|
| `docker-compose up -d` | Start container in background |
| `docker-compose down` | Stop and remove container |
| `docker-compose logs -f` | View live logs |
| `docker-compose restart` | Restart container |
| `docker-compose build --no-cache` | Rebuild image |
```

--------------------------------

### Get All Groups - WhatsApp API

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Fetches a list of all WhatsApp groups that the current session is a member of. Requires a sessionId.

```bash
curl -X POST http://localhost:3000/api/whatsapp/groups \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "mysession"}'
```

--------------------------------

### Get Chat History Overview

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieve an overview of chat history, with options to filter by type and limit the number of results.

```APIDOC
## POST /api/whatsapp/chats/overview

### Description
Get an overview of chat history. Allows filtering by chat type (all, personal, group) and pagination.

### Method
POST

### Endpoint
/api/whatsapp/chats/overview

### Parameters
#### Request Body
- **sessionId** (string) - Required - The session ID for the WhatsApp connection.
- **limit** (integer) - Optional - Maximum number of chats to return (default: 50).
- **offset** (integer) - Optional - Number of chats to skip for pagination (default: 0).
- **type** (string) - Optional - Filter by chat type: 'all', 'personal', or 'group' (default: 'all').

### Request Example
```json
{
  "sessionId": "your_session_id",
  "limit": 20,
  "type": "group"
}
```

### Response
#### Success Response (200)
- **chats** (array of objects) - An array of chat objects.
  - **chatId** (string) - The ID of the chat.
  - **name** (string) - The name of the chat.
  - **lastMessage** (object) - Details of the last message.
  - **timestamp** (integer) - Timestamp of the last message.

#### Response Example
```json
{
  "chats": [
    {
      "chatId": "1234567890@s.whatsapp.net",
      "name": "John Doe",
      "lastMessage": {
        "fromMe": false,
        "text": "Hello!"
      },
      "timestamp": 1678886400
    }
  ]
}
```
```

--------------------------------

### Manage WhatsApp Session Webhooks via API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Demonstrates how to create, add, remove, and update webhook configurations for a WhatsApp session using cURL commands. These operations allow developers to subscribe to specific events like message reception or connection updates.

```bash
# When creating session with multiple webhooks
curl -X POST http://localhost:3000/api/whatsapp/sessions/mysession/connect \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "userId": "123" },
    "webhooks": [
      { "url": "https://primary-server.com/webhook", "events": ["all"] },
      { "url": "https://analytics.example.com/webhook", "events": ["message"] },
      { "url": "https://backup.example.com/webhook", "events": ["connection.update"] }
    ]
  }'

# Add a webhook to existing session
curl -X POST http://localhost:3000/api/whatsapp/sessions/mysession/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-webhook.com/endpoint",
    "events": ["message", "connection.update"]
  }'

# Remove a webhook
curl -X DELETE http://localhost:3000/api/whatsapp/sessions/mysession/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-webhook.com/endpoint"
  }'

# Update all webhooks
curl -X PATCH http://localhost:3000/api/whatsapp/sessions/mysession/config \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://only-this-one.com/webhook", "events": ["all"] }
    ]
  }'
```

--------------------------------

### Get Chat Info (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves detailed information about a specific chat. Requires session ID and chat ID.

```http
POST /chats/info
```

--------------------------------

### Create WhatsApp Group

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Creates a new WhatsApp group by providing a session ID, group name, and a list of participant phone numbers.

```bash
curl -X POST http://localhost:3000/api/whatsapp/groups/create \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "mysession",
    "name": "My New Group",
    "participants": ["628123456789", "628987654321"]
  }'
```

--------------------------------

### Get Session Status (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves the current status of a specific WhatsApp session. This is useful for monitoring the connection state.

```http
GET /sessions/:sessionId/status
```

--------------------------------

### Style API Help and Footer Components

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Defines the layout and styling for the API help information boxes and the global footer section of the dashboard.

```css
.api-help { background: var(--bg-dark); border: 1px solid var(--border); border-radius: 8px; padding: 12px; margin-top: 12px; font-size: 12px; color: var(--text-muted); }
.footer { background: var(--bg-card); border-top: 1px solid var(--border); padding: 24px; margin-top: 48px; text-align: center; }
.footer-content { max-width: 1400px; margin: 0 auto; display: flex; flex-direction: column; align-items: center; gap: 16px; }
```

--------------------------------

### Get Contacts (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Retrieves a list of contacts, with support for searching and pagination. Requires a session ID and optional limit/offset/search parameters.

```http
POST /contacts
```

--------------------------------

### POST /api/whatsapp/groups/create

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Creates a new WhatsApp group with specified participants.

```APIDOC
## POST /api/whatsapp/groups/create

### Description
Creates a new WhatsApp group with specified participants.

### Method
POST

### Endpoint
http://localhost:3000/api/whatsapp/groups/create

### Parameters
#### Request Body
- **sessionId** (string) - Required - The active session identifier.
- **name** (string) - Required - The name of the new group.
- **participants** (array) - Required - List of participant phone numbers.

### Request Example
{
  "sessionId": "mysession",
  "name": "My New Group",
  "participants": ["628123456789", "628987654321"]
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation.
- **message** (string) - Confirmation message.
- **data** (object) - Created group details.

#### Response Example
{
  "success": true,
  "message": "Group created successfully",
  "data": {
    "groupId": "123456789@g.us",
    "subject": "My New Group"
  }
}
```

--------------------------------

### GET /api/websocket/stats

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves statistics about the WebSocket server, including the total number of active connections and a breakdown of connections per session.

```APIDOC
## GET /api/websocket/stats

### Description
Retrieves WebSocket server statistics including connected clients.

### Method
GET

### Endpoint
`/api/websocket/stats`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:3000/api/websocket/stats
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the statistics.
  - **totalConnections** (integer) - The total number of active WebSocket connections.
  - **sessionRooms** (object) - An object where keys are session IDs and values are the number of connections for that session.

#### Response Example
```json
{
  "success": true,
  "data": {
    "totalConnections": 5,
    "sessionRooms": {
      "mysession": 2,
      "othersession": 1
    }
  }
}
```
```

--------------------------------

### Get Group Metadata - Chatery WhatsApp API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Fetches detailed metadata for a specific group, including its participants, admins, and current settings.

```javascript
body = {
  sessionId: '',
  groupId: '123456789@g.us'
};
helpText = 'ℹ️ Get detailed group info including participants, admins, and settings.';
```

--------------------------------

### Get Chat Info - Chatery WhatsApp API

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Retrieves detailed information about a specific chat or group, including metadata and participant details.

```javascript
body = {
  sessionId: '',
  chatId: '628123456789@s.whatsapp.net'
};
helpText = 'ℹ️ Get detailed information about a chat or group.';
```

--------------------------------

### POST /api/whatsapp/sessions/:sessionId/connect

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Initializes a new WhatsApp session or reconnects an existing one, returning a QR code for authentication.

```APIDOC
## POST /api/whatsapp/sessions/:sessionId/connect

### Description
Creates a new WhatsApp session or reconnects an existing one. Optionally configure metadata and webhooks during creation.

### Method
POST

### Endpoint
/api/whatsapp/sessions/:sessionId/connect

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - Unique identifier for the session

#### Request Body
- **metadata** (object) - Optional - Custom session metadata
- **webhooks** (array) - Optional - List of webhook configurations

### Request Example
{
  "metadata": {"userId": "user123"},
  "webhooks": [{"url": "https://example.com/webhook", "events": ["all"]}]
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of the request
- **data** (object) - Session details including QR code

#### Response Example
{
  "success": true,
  "message": "Session created",
  "data": {
    "sessionId": "mysession",
    "status": "qr_ready",
    "qrCode": "data:image/png;base64,..."
  }
}
```

--------------------------------

### Get Group Metadata

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves detailed information about a specific WhatsApp group, including the owner, size, and a list of participants with their admin status.

```bash
curl -X POST http://localhost:3000/api/whatsapp/groups/metadata \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "mysession",
    "groupId": "123456789@g.us"
  }'
```

--------------------------------

### Create/Connect Session (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Creates a new WhatsApp session or connects to an existing one. This endpoint can optionally accept metadata and webhook configurations in the request body. The response includes a QR code if a new session is initiated.

```http
POST /sessions/:sessionId/connect
```

```json
{
  "metadata": {
    "userId": "user123",
    "plan": "premium",
    "customField": "any value"
  },
  "webhooks": [
    { "url": "https://your-server.com/webhook", "events": ["all"] },
    { "url": "https://backup-server.com/webhook", "events": ["message"] }
  ]
}
```

--------------------------------

### Get Profile Picture URL - WhatsApp API

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Retrieves the URL for a contact's WhatsApp profile picture based on their phone number.

```bash
curl -X POST http://localhost:3000/api/whatsapp/chats/profile-picture \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "mysession",
    "phone": "628123456789"
  }'
```

--------------------------------

### Docker Volumes

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Information about Docker volumes used for data persistence in Chatery WhatsApp.

```APIDOC
## Docker Volumes

The following data is persisted across container restarts:

| Volume | Path | Description |
|---|---|---|
| `chatery_sessions` | `/app/sessions` | WhatsApp session data |
| `chatery_media` | `/app/public/media` | Received media files |
| `chatery_store` | `/app/store` | Message history store |
```

--------------------------------

### Retrieve Session QR Code

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Fetches the authentication QR code for a session. Supports returning base64 encoded JSON or a direct PNG image file.

```bash
curl -X GET http://localhost:3000/api/whatsapp/sessions/mysession/qr \
  -H "X-Api-Key: your_api_key"

curl -X GET http://localhost:3000/api/whatsapp/sessions/mysession/qr/image \
  -H "X-Api-Key: your_api_key" \
  --output qr.png
```

--------------------------------

### Get Contacts - WhatsApp API

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Fetches the list of contacts associated with the WhatsApp session. Supports pagination and searching by name or phone number.

```bash
curl -X POST http://localhost:3000/api/whatsapp/contacts \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "mysession",
    "limit": 100,
    "offset": 0,
    "search": "john"
  }'
```

--------------------------------

### Get Chat Messages - WhatsApp API

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Fetches message history for a specific chat, supporting pagination with a cursor. Requires sessionId and chatId.

```bash
curl -X POST http://localhost:3000/api/whatsapp/chats/messages \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "mysession",
    "chatId": "628123456789@s.whatsapp.net",
    "limit": 50,
    "cursor": null
  }'
```

--------------------------------

### Create Group (HTTP)

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/README.md

Creates a new WhatsApp group with a specified name and a list of initial participants. Requires session ID.

```http
POST /groups/create
```

--------------------------------

### Manage WhatsApp Group Settings

Source: https://github.com/farinchan/chatery_whatsapp/blob/main/public/dashboard.html

Handles different group setting configurations such as announcement mode, member permissions for sending messages, and group info editing permissions. It dynamically sets the request body and help text based on the specified path.

```javascript
if (path.includes('/groups/settings')) { body = { sessionId: '', groupId: '123456789@g.us', setting: 'announcement' }; helpText = 
`⚙️ <code>setting</code> options:<br> • <code>announcement</code> - Only admins can send messages<br> • <code>not_announcement</code> - All members can send<br> • <code>locked</code> - Only admins can edit group info<br> • <code>unlocked</code> - All members can edit group info
`; } else if (path.includes('/groups/picture')) { body = { sessionId: '', groupId: '123456789@g.us', imageUrl: 'https://example.com/group-pic.jpg' }; helpText = '🖼️ Update group profile picture. Image should be square.'; } else if (path.includes('/groups/invite-code')) { body = { sessionId: '', groupId: '123456789@g.us' }; helpText = '🔗 Get the current invite link for the group.'; } else if (path.includes('/groups/revoke-invite')) { body = { sessionId: '', groupId: '123456789@g.us' }; helpText = '🔄 Revoke current invite link and generate a new one.'; }
```

--------------------------------

### Get WhatsApp Session Status

Source: https://context7.com/farinchan/chatery_whatsapp/llms.txt

Returns the current connection status and metadata for a specific session ID. Useful for monitoring session health.

```bash
curl -X GET http://localhost:3000/api/whatsapp/sessions/mysession/status \
  -H "X-Api-Key: your_api_key"
```