### Manual Waporta Setup: Start Docker Containers

Source: https://github.com/iniadil/waporta/blob/main/README.md

After cloning and configuring the .env file, start the Waporta Docker containers using the provided command.

```bash
docker compose up -d
```

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

### Start Waporta Server

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Use npm or Docker Compose to start the development server.

```shell
npm run dev
```

```shell
docker compose up -d
```

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

### Clone and Install Dependencies

Source: https://github.com/iniadil/waporta/blob/main/CONTRIBUTING.md

Steps to clone the repository, install npm dependencies, and set up the environment variables.

```bash
git clone https://github.com/iniadil/waporta.git
cd waporta
npm install
cp .env.example .env
# Edit .env: set DASHBOARD_USERNAME and DASHBOARD_PASSWORD
```

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

### Install and Run Waporta with a Single Command

Source: https://github.com/iniadil/waporta/blob/main/README.md

Use this command to quickly install and run Waporta. It automates the cloning, credential setup, and container startup process.

```bash
curl -fsSL https://raw.githubusercontent.com/iniadil/waporta/main/install.sh | sh
```

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

### Start Server with npm

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Starts the Waporta development server using npm. Ensure your .env file is configured.

```bash
npm run dev
```

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

### Session Lifecycle Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Illustrates the state transitions of a WhatsApp session from starting to connected, and when sending messages becomes allowed.

```text
POST /sessions/{id}           → status: "starting"
  ↓ (scan QR code)
GET /sessions/{id}            → status: "connecting"
  ↓ (wait for onConnected)
GET /sessions/{id}            → status: "connected" + user object
POST /send/*                  → now allowed
```

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

### Install Waporta without Docker

Source: https://github.com/iniadil/waporta/blob/main/README.md

Clones the Waporta repository, installs dependencies using npm, and copies the environment example file. Ensure Node.js 20+ is installed, as pnpm and yarn are not supported.

```bash
git clone https://github.com/iniadil/waporta.git
cd waporta
npm install
cp .env.example .env
# edit .env with your credentials
```

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

### Start Server with Docker Compose

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Starts the Waporta server and its dependencies using Docker Compose. Ensure your .env file is configured.

```bash
docker compose up -d
```

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

### Rate Limit & Warm-Up Behavior Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Illustrates the rate limiting and warm-up behavior with example defaults for `SEND_WARMUP_MS`, `SEND_RATE_MAX`, and `SEND_RATE_WINDOW_MS`.

```text
State | Max Sends | Cooldown | Response 
|-----------|-----------|----------|----------|
Warming up | 0 | `SEND_WARMUP_MS` after connect | 429 with `retryAfterMs` 
Rate limited | `SEND_RATE_MAX` per `SEND_RATE_WINDOW_MS` | Window slides | 429 with `retryAfterMs` 
Ready | Unlimited (subject to WhatsApp's own limits) | — | 200 OK 

Example with defaults (`SEND_WARMUP_MS=300000`, `SEND_RATE_MAX=20`, `SEND_RATE_WINDOW_MS=60000`):
1. Session connects at T=0
2. Sends are rejected with 429 until T ≥ 300 seconds
3. At T=300+: sends allowed, but max 20 per minute
4. At T=360: oldest send drops out of window, new send allowed
```

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

### Build for Production

Source: https://github.com/iniadil/waporta/blob/main/CONTRIBUTING.md

Commands to build the dashboard static files and start the production server.

```bash
npm run dashboard:build  # build dashboard static files
npm run start            # build backend + serve everything at :3000
```

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

### API Key Store File Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/03-types.md

An example JSON array representing the API key store, showing id, name, key, and creation timestamp.

```json
[
  {
    "id": "a1b2c3d4",
    "name": "Production",
    "key": "wap_abcd1234efgh5678ijkl9012mnop",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]
```

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

### Run Development Server

Source: https://github.com/iniadil/waporta/blob/main/CONTRIBUTING.md

Command to start the backend and dashboard in development mode with hot reloading.

```bash
npm run dev:all
```

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

### Webhook URL Store File Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/03-types.md

An example JSON object representing the webhook URL store file, showing version and record structure.

```json
{
  "version": 1,
  "records": [
    {
      "id": "a1b2c3d4e5f6a7b8",
      "sessionId": "my-session",
      "url": "https://example.com/webhooks/whatsapp",
      "normalizedUrl": "https://example.com/webhooks/whatsapp",
      "enabled": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

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

### Start WhatsApp Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Use cURL to perform a POST request to start a WhatsApp session with a specified ID.

```shell
curl -X POST http://localhost:3000/api/whatsapp/sessions/{id} ...
```

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

### Start Session Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Response indicating that a new WhatsApp session has started and is initiating QR code generation.

```json
{
  "status": "starting",
  "sessionId": "my-session"
}
```

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

### Start a Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Initiates a new WhatsApp session with a specified session ID.

```APIDOC
## Start a Session

### Description
This endpoint starts a new WhatsApp session identified by a unique `sessionId`.

### Method
POST

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

### Headers
- **X-API-Key**: `wap_...` (Your obtained API key)
- **Content-Type**: `application/json`

### Response Example (Success)
```json
{
  "status": "starting",
  "sessionId": "my-session"
}
```
```

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

### POST /api/whatsapp/sessions/{sessionId}

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Starts a WhatsApp session. Requires Dual authentication.

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

### Description
Starts a WhatsApp session with the specified session ID.

### Method
POST

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

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session to start.

### Auth
Dual

### Response
#### Success Response (200)
- **status** (string) - The status of the session, e.g., "starting".
- **sessionId** (string) - The ID of the session.

### Response Example
{
  "status": "starting",
  "sessionId": "session1"
}
```

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

### Manual Waporta Setup: Clone and Configure

Source: https://github.com/iniadil/waporta/blob/main/README.md

Manually set up Waporta by cloning the repository and configuring environment variables. Ensure you set your dashboard credentials in the .env file.

```bash
git clone https://github.com/iniadil/waporta.git
cd waporta
cp .env.example .env          # set DASHBOARD_USERNAME and DASHBOARD_PASSWORD
```

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

### API Key Authentication Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Demonstrates how to use an API key for authentication, often used for programmatic access.

```http
X-API-Key: wap_...
```

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

### GET /api/keys

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Lists all available API keys.

```APIDOC
## GET /api/keys

### Description
Retrieves a list of all generated API keys. This endpoint is useful for managing and auditing API key usage.

### Method
GET

### Endpoint
/api/keys

### Response
#### Success Response (200)
- Returns an array of API key objects. Each object typically contains details like key ID and name.

#### Response Example
[
  {
    "id": "key_123",
    "name": "My App Key"
  }
]
```

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

### Start WhatsApp Session with Pairing Code

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Starts a WhatsApp session using a phone number and returns a pairing code for confirmation. Requires Dual authentication.

```typescript
async (c) => {
  const { sessionId } = c.req.valid("param")
  const { phoneNumber } = c.req.valid("json")

  const pairingCode = await new Promise<string>((resolve, reject) => {
    wa.startSessionWithPairingCode(sessionId, {
      phoneNumber,
      onPairingCode: (code) => resolve(code),
    }).catch(reject)
  })

  return c.json({
    status: "waiting_for_confirmation",
    sessionId,
    pairingCode,
  })
}
```

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

### Example Webhook POST Body

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

This is an example of the JSON structure sent in the request body for webhook notifications of delivery failures.

```json
{
  "sessionId": "my-session",
  "to": "6281234567890",
  "messageType": "text",
  "error": "connection timeout",
  "attempts": 3,
  "timestamp": "2024-01-01T12:34:56.789Z"
}
```

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

### Start WhatsApp Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Initiates a new WhatsApp session for a given session ID. This is the first step to connecting a WhatsApp number.

```bash
curl -X POST \
  http://localhost:3000/api/whatsapp/sessions/my_session \
  -H "X-API-Key: wap_..."
```

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

### Start WhatsApp Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Initiates a WhatsApp session for a given session ID. Requires Dual authentication.

```typescript
async (c) => {
  const { sessionId } = c.req.valid("param")
  setPendingSession(sessionId)
  await wa.startSession(sessionId)
  return c.json({ status: "starting", sessionId })
}
```

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

### Webhook Payload Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Example of a POST request payload received by your webhook URL when a message is received.

```json
POST https://example.com/webhooks/whatsapp
Content-Type: application/json

{
  "event": "message.received",
  "sessionId": "my-session",
  "messageId": "ABCDEF123456",
  "sender": "6281234567890@s.whatsapp.net",
  "recipient": "6289876543210@s.whatsapp.net",
  "timestamp": 1700000000,
  "messageType": "text",
  "content": {
    "text": "Hello!"
  },
  "raw": { ... }
}
```

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

### Start a WhatsApp Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Initiate a new WhatsApp session using the API. This command requires your API key and a unique session ID.

```bash
curl -X POST http://localhost:3000/api/whatsapp/sessions/my-session \
  -H "X-API-Key: wap_..." \
  -H "Content-Type: application/json"

# Response: {"status":"starting","sessionId":"my-session"}
```

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

### Webhook Flow Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Describes the sequence of events when an incoming WhatsApp message triggers a webhook dispatch.

```text
Incoming WhatsApp message
  ↓
wa-multi-session onMessageReceived callback
  ↓
Dispatch to all enabled webhooks
  ↓
POST to https://your-url with WebhookMessagePayload
  ↓
(fire-and-forget; failures logged but don't block)
```

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

### Webhook URL Normalization Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Demonstrates how webhook URLs are normalized before storage, including lowercasing, port omission, and trailing slash removal.

```text
Input:  https://EXAMPLE.COM:443/webhook?key=value
Stored: https://example.com/webhook?key=value
```

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

### Bearer Token Authentication Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Shows how to use a Bearer token for authentication, typically obtained from a login endpoint.

```http
Authorization: Bearer <token>
```

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

### WhatsApp Session Connecting Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response when a WhatsApp session is in the process of connecting.

```json
{
  "sessionId": "my-session",
  "status": "connecting",
  "user": null
}
```

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

### WhatsApp Session Not Found Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response when a requested WhatsApp session does not exist.

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

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

### GET /api/keys

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

List all API keys associated with the account. Keys are masked for security.

```APIDOC
## GET /api/keys

### Description
List all API keys (masked).

### Method
GET

### Endpoint
/api/keys

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the API key.
- **name** (string) - The name given to the API key.
- **maskedKey** (string) - The masked version of the API key.
- **createdAt** (string) - The date and time the API key was created.

#### Response Example
```json
[
  {
    "id": "a1b2c3d4",
    "name": "Production",
    "maskedKey": "wap_abcd1234efgh...",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]
```
```

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

### npm Overrides Configuration

Source: https://github.com/iniadil/waporta/blob/main/CONTRIBUTING.md

Example of how npm overrides are used in package.json to pin specific dependency versions.

```json
"overrides": { "wa-multi-session": { "baileys": "7.0.0-rc13" } }
```

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

### WhatsApp Session Connected Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response for a successfully connected WhatsApp session.

```json
{
  "sessionId": "my-session",
  "status": "connected",
  "user": {
    "id": "6281234567890@s.whatsapp.net",
    "name": "John Doe",
    "lid": "optional-lid-value"
  }
}
```

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

### Webhook Payload Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Illustrates the structure of the JSON payload received by your webhook URL when a message is received.

```APIDOC
## Webhook Payload Example

### Description
This is an example of the JSON payload your webhook URL will receive when a message is received via WhatsApp.

### Method
POST

### Endpoint
Your configured webhook URL (e.g., `https://example.com/webhooks/whatsapp`)

### Request Body
- **event** (string) - The type of event (e.g., "message.received").
- **sessionId** (string) - The ID of the session that received the message.
- **messageId** (string) - The unique identifier for the received message.
- **sender** (string) - The sender's WhatsApp ID.
- **recipient** (string) - The recipient's WhatsApp ID.
- **timestamp** (integer) - The Unix timestamp when the message was received.
- **messageType** (string) - The type of the message (e.g., "text", "image").
- **content** (object) - The actual content of the message, structured by type.
- **raw** (object) - Raw payload data from WhatsApp.

### Request Example
```json
{
  "event": "message.received",
  "sessionId": "my-session",
  "messageId": "ABCDEF123456",
  "sender": "6281234567890@s.whatsapp.net",
  "recipient": "6289876543210@s.whatsapp.net",
  "timestamp": 1700000000,
  "messageType": "text",
  "content": {
    "text": "Hello!"
  },
  "raw": { ... }
}
```

### Response
Any 2xx status code indicates success. Other status codes will be logged as failures but will not block subsequent webhook deliveries.
```

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

### POST /api/whatsapp/sessions/{sessionId}/pairing-code

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Initiates session start using a pairing code. Requires Dual authentication.

```APIDOC
## POST /api/whatsapp/sessions/{sessionId}/pairing-code

### Description
Starts a WhatsApp session using a phone number and returns a pairing code for confirmation.

### Method
POST

### Endpoint
/api/whatsapp/sessions/{sessionId}/pairing-code

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

#### Request Body
- **phoneNumber** (string) - Required - The phone number to associate with the session.

### Auth
Dual

### Response
#### Success Response (200)
- **status** (string) - The status of the pairing process, e.g., "waiting_for_confirmation".
- **sessionId** (string) - The ID of the session.
- **pairingCode** (string) - The pairing code to be confirmed by the user.

### Response Example
{
  "status": "waiting_for_confirmation",
  "sessionId": "session1",
  "pairingCode": "123456"
}
```

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

### POST /api/whatsapp/sessions/{sessionId}

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Start a new WhatsApp session or initiate QR code generation for a given session ID. Requires dual authentication.

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

### Description
Start a new session (initiate QR code generation).

### Method
POST

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

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

### Headers
- **Authorization** (string) - Required - Bearer token or API Key for authentication.

### Response
#### Success Response (200 OK)
- **status** (string) - The status of the session initiation (e.g., "starting").
- **sessionId** (string) - The identifier of the session.

#### Response Example
```json
{
  "status": "starting",
  "sessionId": "my-session"
}
```
```

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

### Set Default API Key

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Optionally set a static API key for initial setup or single-key deployments. If set, it must be prefixed with 'wap_'.

```env
DEFAULT_API_KEY=wap_static_key_here
```

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

### Set Static API Key for Waporta

Source: https://github.com/iniadil/waporta/blob/main/README.md

Configure a static API key by setting the DEFAULT_API_KEY in your .env file before starting Waporta. This key will be used for API authentication.

```env
DEFAULT_API_KEY=wap_your_static_key_here
```

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

### Example Backoff Sequence for Retries

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Illustrates the exponential backoff with jitter sequence for retrying message deliveries, including wait times between attempts.

```text
Initial attempt fails
├─ Wait 3000ms + jitter → Attempt 2
├─ Attempt 2 fails
├─ Wait 6000ms + jitter → Attempt 3
└─ Attempt 3 fails → RetriesExhaustedError
```

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

### Get QR Code for Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Retrieves the QR code necessary for WhatsApp Web or device pairing for a given session.

```APIDOC
## Get the QR Code

### Description
Fetches the QR code image data required to link a WhatsApp client to the session. This is typically scanned using the WhatsApp application on a mobile device.

### Method
GET

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

### Headers
- **X-API-Key**: `wap_...` (Your obtained API key)

### Response Example (Success)
```json
{
  "qr": "data:image/png;base64, ... "
}
```
**Note:** Scan this QR code with WhatsApp on your phone, or use the pairing code alternative if available.
```

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

### Failure Notification Flow Example

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Details the process of notifying users via email and webhooks when a message fails to send after multiple retries.

```text
Message send fails after 3 retries
  ↓
Compile FailureDetails object
  ↓
Call registry.notifyAll() (async, non-blocking)
  ↓
Email & webhook notifiers (if configured)
```

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

### Manual Waporta Setup: Edit .env for Credentials

Source: https://github.com/iniadil/waporta/blob/main/README.md

Edit the .env file to set your desired dashboard username and password. These credentials are required for accessing the Waporta dashboard.

```env
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=your-secure-password
```

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

### Build and Generate Swagger

Source: https://github.com/iniadil/waporta/blob/main/CONTRIBUTING.md

Run these commands to build the project, generate Swagger documentation, build the dashboard, and check for git diffs. Ensure all parts of the project are up-to-date and checked for consistency.

```bash
npm run build
npm run gen:swagger
cd dashboard && npm run build
git diff --check
```

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

### Create API Key

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Create a new API key for your account. Provide a name for the key and authenticate with a bearer token.

```bash
curl -X POST http://localhost:3000/api/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'
```

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

### Obtain API Key (Dynamic)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Demonstrates how to generate an API key dynamically by first logging in to obtain a token, and then using that token to create a new API key.

```APIDOC
## Obtain API Key (Dynamic)

### Description
This process involves two steps: first, authenticating to obtain a JWT token, and second, using that token to create a new API key.

### Step 1: Login to Dashboard

#### Method
POST

#### Endpoint
`http://localhost:3000/auth/login`

#### Request Body
```json
{
  "username": "admin",
  "password": "changeme"
}
```

#### Response Example (Success)
```json
{
  "token": "hexadecimal_token_string"
}
```

### Step 2: Create an API Key

#### Method
POST

#### Endpoint
`http://localhost:3000/api/keys`

#### Headers
- **Authorization**: `Bearer <token>` (from Step 1)
- **Content-Type**: `application/json`

#### Request Body
```json
{
  "name": "my-key"
}
```

#### Response Example (Success)
```json
{
  "id": "...",
  "name": "my-key",
  "key": "wap_...",
  "createdAt": "..."
}
```
**Note:** The `key` value is shown once only. Save it securely.
```

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

### GET /api/whatsapp/sessions

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Lists all available WhatsApp sessions. Requires Dual authentication.

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

### Description
Lists all available WhatsApp sessions.

### Method
GET

### Endpoint
/api/whatsapp/sessions

### Auth
Dual

### Response
#### Success Response (200)
- **sessions** (array) - A list of session IDs.

### Response Example
{
  "sessions": ["session1", "session2"]
}
```

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

### GET /api/whatsapp/sessions/{sessionId}/webhooks

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Lists all webhooks for a session. Requires Dual authentication.

```APIDOC
## GET /api/whatsapp/sessions/{sessionId}/webhooks

### Description
Lists all configured webhooks for a specific WhatsApp session.

### Method
GET

### Endpoint
/api/whatsapp/sessions/{sessionId}/webhooks

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

### Auth
Dual

### Response
#### Success Response (200)
- **webhooks** (array) - A list of webhook objects.
  - **id** (string) - The ID of the webhook.
  - **url** (string) - The URL of the webhook.
  - **events** (array of strings) - The events the webhook is subscribed to.

### Response Example
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "http://your-app.com/webhook",
      "events": ["message"]
    }
  ]
}
```

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

### WebhookUrlStore Constructor

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/06-modules.md

Initializes the WebhookUrlStore for file-based storage of webhook URLs.

```typescript
constructor()
```

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

### Check Server Logs (npm)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Command to view real-time logs when running Waporta directly using npm.

```bash
# If running via npm
npm run dev
```

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

### Project File Organization

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/INDEX.md

Provides a hierarchical view of the project's directory structure and key files.

```bash
/workspace/home/output/
├── README.md                      (overview & navigation)
├── INDEX.md                       (this file)
├── 01-project-overview.md         (architecture)
├── 02-http-api.md                 (endpoints)
├── 03-types.md                    (type definitions)
├── 04-configuration.md            (configuration)
├── 05-errors.md                   (error handling)
├── 06-modules.md                  (function reference)
├── 07-routes.md                   (handler implementations)
└── 08-quick-reference.md          (code examples)
```

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

### GET /api/whatsapp/check

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Checks the validity of a WhatsApp recipient number. Requires Dual authentication.

```APIDOC
## GET /api/whatsapp/check

### Description
Checks if a given phone number is a valid WhatsApp recipient.

### Method
GET

### Endpoint
/api/whatsapp/check

### Query Parameters
- **phoneNumber** (string) - Required - The phone number to check.

### Auth
Dual

### Response
#### Success Response (200)
- **isValid** (boolean) - Indicates if the phone number is a valid WhatsApp recipient.

### Response Example
{
  "isValid": true
}
```

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

### Build Waporta Project

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Command to build the Waporta project for production.

```shell
npm run build
```

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

### Obtain API Key (Static)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Use a static API key if it's already configured in your environment variables.

```shell
X-API-Key: wap_<value from DEFAULT_API_KEY>
```

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

### Get Webhook Records Snapshot

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/06-modules.md

Returns a shallow copy of all currently stored webhook records.

```typescript
snapshot(): WebhookUrlRecord[]
```

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

### GET /api/whatsapp/sessions/{sessionId}/webhooks

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Lists all registered webhook URLs for a specific WhatsApp session.

```APIDOC
## GET /api/whatsapp/sessions/{sessionId}/webhooks

### Description
Retrieves a list of all webhook URLs configured for a given WhatsApp session. Requires the webhook store to be operational.

### Method
GET

### Endpoint
/api/whatsapp/sessions/{sessionId}/webhooks

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the WhatsApp session whose webhooks are to be listed.

### Response
#### Success Response (200)
- Returns an array of webhook records associated with the specified session.

#### Response Example
[
  {
    "id": "wh_abc",
    "sessionId": "session_123",
    "url": "https://example.com/webhook"
  }
]

#### Error Response (500)
- **error** (string) - Indicates that the webhook URL store is unavailable.
```

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

### GET /auth/check

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Verify that a Bearer token is valid. Returns a success response if the token is valid.

```APIDOC
## GET /auth/check

### Description
Verify that a Bearer token is valid.

### Method
GET

### Endpoint
/auth/check

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200 OK)
- **ok** (boolean) - Indicates the token is valid.

#### Response Example
```json
{
  "ok": true
}
```

#### Error Response (401 Unauthorized)
- **error** (string) - Indicates the token is invalid or missing.

#### Response Example
```json
{
  "error": "Unauthorized"
}
```
```

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

### Configure Warm-Up Window for Message Sending

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Set the time in milliseconds to wait after a WhatsApp session connects before allowing message sends. Defaults to 300000ms (5 minutes). Setting to 0 disables warm-up, which is not recommended.

```env
SEND_WARMUP_MS=600000
```

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

### WebhookUrlManager Constructor

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/06-modules.md

Initializes the WebhookUrlManager with a store.

```typescript
constructor(store: WebhookUrlStore)
```

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

### WhatsApp Send Message Success Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response indicating a message has been successfully sent.

```json
{
  "status": "sent"
}
```

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

### WhatsApp Session Deletion Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response upon successful deletion of a WhatsApp session.

```json
{
  "status": "deleted",
  "sessionId": "my-session"
}
```

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

### Obtain API Key (Dynamic Generation)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Dynamically generate an API key by logging into the dashboard and creating a new key. Save the generated key securely as it is shown only once.

```bash
# 1. Login to dashboard
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}'

# Response:
# {"token":"hexadecimal_token_string"}

# 2. Create an API key
curl -X POST http://localhost:3000/api/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-key"}'

# Response:
# {
#   "id":"",
#   "name":"my-key",
#   "key":"wap_",
#   "createdAt":""
# }
# Save the "key" value — it's shown once only!
```

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

### Configure Failure Notifications

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Set up SMTP server details, user credentials, and notification email/webhook for failure alerts.

```env
SMTP_HOST=smtp.example.com
SMTP_USER=...
SMTP_PASS=...
NOTIFY_EMAIL=alerts@example.com
NOTIFY_WEBHOOK_URL=https://example.com/webhooks/failures
```

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

### GET /auth/check

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Checks the validity of the current authentication token. Assumes middleware has already validated the token.

```APIDOC
## GET /auth/check

### Description
Verifies if the current authentication token is valid. This endpoint is typically used to confirm an active session.

### Method
GET

### Endpoint
/auth/check

### Response
#### Success Response (200)
- **ok** (boolean) - Always true, indicating the token is valid.

#### Response Example
{
  "ok": true
}
```

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

### GET /api/whatsapp/check

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Checks if a WhatsApp number exists. It takes session details and the target number as input.

```APIDOC
## GET /api/whatsapp/check

### Description
Verifies the existence of a WhatsApp number. This is useful for checking if a contact is active on WhatsApp before sending a message.

### Method
GET

### Endpoint
/api/whatsapp/check

### Parameters
#### Query Parameters
- **sessionId** (string) - Required - The identifier for the WhatsApp session.
- **to** (string) - Required - The WhatsApp number to check.
- **isGroup** (string) - Optional - A string indicating 'true' if checking for a group, otherwise false or omitted.

### Response
#### Success Response (200)
- **exists** (boolean) - True if the WhatsApp number exists, false otherwise.

#### Response Example
{
  "exists": true
}
```

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

### Check Server Logs (Docker Compose)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Command to view real-time logs from the Waporta service when running via Docker Compose.

```bash
# If running via Docker Compose
docker-compose logs -f waporta
```

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

### Get QR Code Response (Not Available)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Response indicating that no QR code is currently available for the session.

```json
{
  "qr": null
}
```

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

### Run Waporta in Development or Production (without Docker)

Source: https://github.com/iniadil/waporta/blob/main/README.md

Commands to run Waporta in development mode with hot reloading for backend and dashboard, or in production mode.

```bash
npm run dev:all    # dev: backend + dashboard (hot reload)
```

```bash
npm run start      # production
```

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

### Sessions API

Source: https://github.com/iniadil/waporta/blob/main/README.md

Endpoints for managing WhatsApp sessions, including listing, starting, checking status, and deleting sessions.

```APIDOC
## Sessions API

Base URL: `http://localhost:3000/api/whatsapp`

### List all sessions

- **Method**: `GET`
- **Endpoint**: `/sessions`

### Start a new session

- **Method**: `POST`
- **Endpoint**: `/sessions/:sessionId`

### Start via pairing code

- **Method**: `POST`
- **Endpoint**: `/sessions/:sessionId/pairing-code`

### Get session status

- **Method**: `GET`
- **Endpoint**: `/sessions/:sessionId`

### Get QR code

- **Method**: `GET`
- **Endpoint**: `/sessions/:sessionId/qr`

### Delete and logout session

- **Method**: `DELETE`
- **Endpoint**: `/sessions/:sessionId`
```

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

### Initialize Webhook Store

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/06-modules.md

Loads webhook URLs from a JSON file. It handles both legacy and versioned formats and sets the operational status based on load success.

```typescript
init(): void
```

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

### WhatsApp Send Message Session Unavailable Response

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Example JSON response when the WhatsApp session is unavailable or disconnected.

```json
{
  "error": "session_unavailable",
  "message": "Session disconnected unexpectedly",
  "retryAfterMs": null
}
```

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

### POST /auth/login

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Logs in a user to the dashboard. It validates credentials against environment variables and issues a token upon success.

```APIDOC
## POST /auth/login

### Description
Authenticates a user for dashboard access. Upon successful validation of username and password, it generates and returns an authentication token.

### Method
POST

### Endpoint
/auth/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
{
  "username": "admin",
  "password": "changeme"
}

### Response
#### Success Response (200)
- **token** (string) - The authentication token for subsequent requests.

#### Response Example
{
  "token": "a1b2c3d4e5f6..."
}

#### Error Response (401)
- **error** (string) - Indicates invalid credentials.

#### Response Example
{
  "error": "Invalid credentials"
}
```

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

### GET /api/whatsapp/sessions/{sessionId}

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Retrieves the status and user information for a specific WhatsApp session. Requires Dual authentication.

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

### Description
Retrieves the status and user information for a specific WhatsApp session.

### Method
GET

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

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

### Auth
Dual

### Response
#### Success Response (200)
- **sessionId** (string) - The ID of the session.
- **status** (string) - The current status of the session.
- **user** (object | null) - User information if available.
  - **id** (string) - User ID.
  - **name** (string) - User name.
  - **lid** (string) - User LID.

### Response Example
{
  "sessionId": "session1",
  "status": "connected",
  "user": {
    "id": "1234567890@s.whatsapp.net",
    "name": "John Doe",
    "lid": "lid123"
  }
}
```

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

### Create API Key

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Generate a new API key for programmatic access. Store this key securely as it is shown only once.

```bash
curl -X POST \
  http://localhost:3000/api/keys \
  -H "Authorization: Bearer <your_bearer_token>"
```

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

### Get QR Code Response (Available)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Response containing the Base64 encoded QR code for session pairing.

```json
{
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}
```

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

### Configure Email Notifications

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/04-configuration.md

Set these environment variables to enable email notifications. Ensure both SMTP_HOST and NOTIFY_EMAIL are provided. Emails are sent asynchronously.

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=waporta@example.com
NOTIFY_EMAIL=alerts@example.com
```

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

### GET /api/whatsapp/sessions/{sessionId}/qr

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Retrieves the QR code for a given WhatsApp session. Requires Dual authentication.

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

### Description
Retrieves the QR code for a given WhatsApp session, used for initial pairing.

### Method
GET

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

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session.

### Auth
Dual

### Response
#### Success Response (200)
- **qr** (string) - The QR code string.

### Response Example
{
  "qr": "QR_CODE_STRING"
}
```

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

### POST /api/keys

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Create a new API key with a specified name. The full key is returned upon creation.

```APIDOC
## POST /api/keys

### Description
Create a new API key.

### Method
POST

### Endpoint
/api/keys

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **name** (string) - Required - The name for the new API key.

### Request Example
```json
{
  "name": "Production"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the new API key.
- **name** (string) - The name of the new API key.
- **key** (string) - The full, unmasked API key.
- **createdAt** (string) - The date and time the API key was created.

#### Response Example
```json
{
  "id": "a1b2c3d4",
  "name": "Production",
  "key": "wap_abcd1234efgh5678ijkl9012mnop",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```

#### Error Response (400 Bad Request)
- **error** (string) - Indicates that the name is required.

#### Response Example
```json
{
  "error": "Name is required"
}
```
```

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

### GET /api/whatsapp/check

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Check if a phone number or group JID exists on WhatsApp. Requires a session ID and the target identifier.

```APIDOC
## GET /api/whatsapp/check

### Description
Check if a phone number exists on WhatsApp.

### Method
GET

### Endpoint
/api/whatsapp/check

### Parameters
#### Query Parameters
- **sessionId** (string) - yes - Session identifier
- **to** (string) - yes - Phone number or JID to check
- **isGroup** (string) - no - If `"true"`, treat as group JID

### Request Example
```
GET /api/whatsapp/check?sessionId=my-session&to=6281234567890
GET /api/whatsapp/check?sessionId=my-session&to=120363178954856@g.us&isGroup=true
```

### Response
#### Success Response (200 OK)
- **exists** (boolean) - Description: Indicates if the number/JID exists

#### Response Example
```json
{
  "exists": true
}
```
```

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

### List API Keys

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Retrieve a list of all API keys associated with your account. Requires authentication with a bearer token.

```bash
curl http://localhost:3000/api/keys \
  -H "Authorization: Bearer <token>"
```

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

### GET /api/whatsapp/sessions

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

List all available WhatsApp session IDs. Requires either Bearer token or API Key authentication.

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

### Description
List all session IDs.

### Method
GET

### Endpoint
/api/whatsapp/sessions

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
OR
- **X-API-Key** (string) - Required - API Key for authentication.

### Response
#### Success Response (200 OK)
- **sessions** (array) - An array of session IDs.

#### Response Example
```json
{
  "sessions": ["my-session", "another-session"]
}
```
```

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

### Listen to Webhooks with Node.js and Express

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Sets up a simple Node.js server using Express to receive and log incoming WhatsApp messages via webhooks. Ensure your server is accessible from the internet and register the webhook URL for your session.

```typescript
// Simple Node.js webhook receiver
import express from "express";
const app = express();
app.use(express.json());

app.post("/webhooks/whatsapp", (req, res) => {
  const payload = req.body;
  console.log(
    `Message from ${payload.sender}: ${payload.content?.text || "(media)"}`,
    `[session: ${payload.sessionId}]`
  );
  res.status(200).send({ ok: true });
});

app.listen(3001, () => console.log("Webhook receiver on :3001"));
```

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

### Get WhatsApp Session QR Code

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Use cURL to retrieve the QR code for a specific WhatsApp session ID.

```shell
curl http://localhost:3000/api/whatsapp/sessions/{id}/qr ...
```

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

### Get WhatsApp Session Status

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Retrieves the status and user information for a specific WhatsApp session. Requires Dual authentication.

```typescript
async (c) => {
  const { sessionId } = c.req.valid("param")
  const session = await wa.getSessionById(sessionId)
  if (!session) return c.json({ error: "Session not found" }, 404)
  const sockUser = session.sock.user
  const user = sockUser
    ? { id: sockUser.id, name: sockUser.name, lid: sockUser.lid }
    : null
  return c.json({ sessionId, status: session.status, user }, 200)
}
```

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

### Production Environment Variables

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Configuration for a production environment, including settings for anti-ban measures, failure notifications, and port.

```env
DASHBOARD_USERNAME=secure-username
DASHBOARD_PASSWORD=very-secure-password
PORT=3000

# Anti-ban: generous warm-up for new accounts
SEND_WARMUP_MS=900000
SEND_RATE_MAX=20
SEND_RATE_WINDOW_MS=60000

# Failure notifications
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerter@example.com
SMTP_PASS=app-password
NOTIFY_EMAIL=ops@example.com
NOTIFY_WEBHOOK_URL=https://example.com/api/waporta-failures
```

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

### Get WhatsApp Session QR Code

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/07-routes.md

Fetches the QR code for a specific WhatsApp session. Requires Dual authentication.

```typescript
async (c) => {
  const { sessionId } = c.req.valid("param")
  const qr = getQR(sessionId)
  return c.json({ qr })
}
```

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

### Get WhatsApp Session Status

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/02-http-api.md

Retrieves the connection status and user information for a given WhatsApp session. Requires an Authorization header.

```http
GET /api/whatsapp/sessions/{sessionId}
Authorization: Bearer <token>
```

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

### Whatsapp Instance (src/wa.ts)

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/06-modules.md

Provides a singleton WhatsApp instance with Baileys integration, supporting multi-session management and various messaging functionalities.

```APIDOC
## Whatsapp Instance (src/wa.ts)

### Description
Provides a singleton WhatsApp instance with Baileys integration, supporting multi-session management and various messaging functionalities. It is configured with SQLiteAdapter for persistence and has autoload enabled by default.

### Methods

#### `getSessionsIds()`
- **Description**: Get all session IDs.
- **Signature**: `async (): Promise<string[]>`

#### `getSessionById(id)`
- **Description**: Get a session by ID.
- **Signature**: `async (id: string): Promise<Session | undefined>`

#### `startSession(id)`
- **Description**: Start a new session (initiate QR).
- **Signature**: `async (id: string): Promise<void>`

#### `deleteSession(id)`
- **Description**: Delete a session.
- **Signature**: `async (id: string): Promise<void>`

#### `isExist(opts)`
- **Description**: Check if recipient exists on WhatsApp.
- **Parameters**:
  - `opts` (object) - Required - Options object containing `sessionId`, `to`, and `isGroup`.
- **Signature**: `async (opts: { sessionId, to, isGroup }): Promise<boolean>`

#### `sendText(opts)`
- **Description**: Send text message.
- **Parameters**:
  - `opts` (object) - Required - Options object containing `sessionId`, `to`, `text`, and `isGroup`.
- **Signature**: `async (opts: { sessionId, to, text, isGroup }): Promise<unknown>`

#### `sendImage(opts)`
- **Description**: Send image message.
- **Parameters**:
  - `opts` (object) - Required - Options object containing `sessionId`, `to`, `media`, `text`, and `isGroup`.
- **Signature**: `async (opts: { sessionId, to, media, text, isGroup }): Promise<unknown>`

#### `sendDocument(opts)`
- **Description**: Send document message.
- **Parameters**:
  - `opts` (object) - Required - Options object containing `sessionId`, `to`, `media`, `filename`, `text`, and `isGroup`.
- **Signature**: `async (opts: { sessionId, to, media, filename, text, isGroup }): Promise<unknown>`

#### `sendTypingIndicator(opts)`
- **Description**: Show typing indicator.
- **Parameters**:
  - `opts` (object) - Required - Options object containing `sessionId`, `to`, and `duration`, and `isGroup`.
- **Signature**: `async (opts: { sessionId, to, duration, isGroup }): Promise<void>`

#### `startSessionWithPairingCode(id, opts)`
- **Description**: Start session with pairing code.
- **Parameters**:
  - `id` (string) - Required.
  - `opts` (object) - Required - Options object containing `phoneNumber` and `onPairingCode` callback.
- **Signature**: `async (id: string, opts: { phoneNumber: string; onPairingCode(code: string): void }): Promise<void>`

### Events

- **`onConnecting(sessionId)`**: Session connecting.
- **`onConnected(sessionId)`**: Session authenticated.
- **`onDisconnected(sessionId)`**: Session lost connection.
- **`onQRUpdated(qrData)`**: QR code updated (contains `{ sessionId, qr }`).
- **`onMessageReceived(msg)`**: Incoming message (triggers webhook dispatch).
```

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

### Get Bearer Token

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/README.md

Obtain a Bearer token for authentication by calling the /auth/login endpoint. This token is used for subsequent API calls.

```bash
curl -X POST \
  http://localhost:3000/auth/login \
  -H 'Content-Type: application/json' \
  -d '{ "username": "your_username", "password": "your_password" }'
```

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

### List Webhook URLs for a Session

Source: https://github.com/iniadil/waporta/blob/main/_autodocs/08-quick-reference.md

Retrieve a list of all registered webhook URLs for a specific WhatsApp session.

```bash
curl http://localhost:3000/api/whatsapp/sessions/my-session/webhooks \
  -H "X-API-Key: wap_..."
```