### Installation

Source: https://zca-cli.dev/docs/index

Instructions on how to install zca-cli globally using different package managers.

```APIDOC
## Installation

Install zca-cli globally using your preferred package manager:

### Using curl
```bash
$ curl -fsSL get.zca-cli.dev/install.sh | bash
```

### Using PowerShell
```powershell
$ irm get.zca-cli.dev/install.ps1 | iex
```

After installation, verify it works by running:

```bash
$ zca --version
```
```

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

### Start zca-cli Server with Custom Port

Source: https://zca-cli.dev/docs/index

Starts the zca-cli server and specifies a custom port for the server to listen on. This allows you to avoid port conflicts or use a preferred port.

```bash
$ zca serve --port 8080

```

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

### Start zca-cli Server to Serve Multiple Zalo Profiles

Source: https://zca-cli.dev/docs/index

Starts the zca-cli server and configures it to serve multiple Zalo profiles. Profiles are specified as a comma-separated list and can be accessed via URL prefixes.

```bash
$ zca serve --accounts work,personal

```

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

### Zalo CLI Multi-Account Setup Workflow

Source: https://zca-cli.dev/docs/index

A shell script demonstrating a multi-account setup workflow for the Zalo CLI. It covers logging in with different profiles, labeling them, setting a default profile, and listing all configured profiles.

```bash
# Step 1: Login to your work account
$ zca --profile work auth login
# Scan QR with your work Zalo

# Step 2: Login to your personal account
$ zca --profile personal auth login
# Scan QR with your personal Zalo

# Step 3: Label your profiles
$ zca account label work "Office Zalo"
$ zca account label personal "My personal Zalo"

# Step 4: Set default profile
$ zca account switch work

# Step 5: List all profiles
$ zca account list
# Output:
#   work (default) - Office Zalo
#   personal - My personal Zalo

# Now you can use them:
$ zca msg send 123 "From work (default)"
$ zca --profile personal msg send 456 "From personal"
```

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

### Start zca-cli Server with Default Options

Source: https://zca-cli.dev/docs/index

Starts the zca-cli server using default configuration settings. The default port is 56789 and the host is localhost.

```bash
$ zca serve

```

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

### Start zca-cli Server with Basic Authentication and Authenticate Request

Source: https://zca-cli.dev/docs/index

Shows how to start the zca-cli server with Basic HTTP authentication and subsequently make an authenticated request using cURL. This method requires encoding the username and password.

```bash
# Start server with Basic auth
$ zca serve --auth-basic admin:password123
. 
# Make authenticated request
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Basic $(echo -n admin:password123 | base64)"

```

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

### Install zca-cli using curl or PowerShell

Source: https://zca-cli.dev/docs/index

Installs zca-cli globally on your system using either a curl script for Linux/macOS or a PowerShell script for Windows. Ensure you have Node.js 18+ and a package manager installed.

```shell
# Using terminal
$ curl -fsSL get.zca-cli.dev/install.sh | bash
.
#or Using PowerShell
$ irm get.zca-cli.dev/install.ps1 | iex
.
```

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

### Start zca-cli Server with Multi-Account and Authentication

Source: https://zca-cli.dev/docs/index

Starts the zca-cli server to serve multiple Zalo profiles with Bearer token authentication and a custom port. This configuration is useful for managing different Zalo accounts securely.

```bash
$ zca serve --accounts work,personal --auth-bearer token --port 8080

```

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

### Start zca-cli Server with Bearer Token and Authenticate Request

Source: https://zca-cli.dev/docs/index

Demonstrates how to start the zca-cli server with Bearer token authentication and then make an authenticated request using cURL. This ensures secure access to the API.

```bash
# Start server with Bearer token
$ zca serve --auth-bearer my-secret-token
. 
# Make authenticated request
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Bearer my-secret-token"

```

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

### Verify zca-cli installation

Source: https://zca-cli.dev/docs/index

Checks if zca-cli has been installed correctly by displaying its current version. This command is run after the installation process.

```shell
$ zca --version
```

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

### Start zca-cli Server with Bearer Token Authentication

Source: https://zca-cli.dev/docs/index

Starts the zca-cli server and requires Bearer token authentication for all incoming requests. A specific token must be provided to access the API.

```bash
$ zca serve --auth-bearer mytoken

```

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

### Production Zalo Listener Setup Script

Source: https://zca-cli.dev/docs/index

A bash script demonstrating a comprehensive production setup for the Zalo listener. It combines webhook integration, prefix filtering, auto-restart, raw JSON output, and specific event filtering for robust and reliable operation. This script is intended for use with process managers like systemd or pm2.

```bash
#!/bin/bash
# Production listener with all options
.
$ zca listen \
$   --webhook "https://api.mybot.com/zalo/webhook" \
$   --prefix "!bot" \
$   --keep-alive \
$   --raw \
$   --events "message,reaction,group_event"
```

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

### Get Account Information (zca-cli)

Source: https://zca-cli.dev/docs/index

Retrieves the current user's account information. Supports JSON output format and includes an example.

```bash
$ zca me info [options]
```

```bash
$ zca me info
```

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

### Get help in zca-cli

Source: https://zca-cli.dev/docs/index

Demonstrates how to access help information for zca-cli commands. This includes general help, help for command groups, and help for specific commands.

```shell
# General help
$ zca --help
.
# Help for a command group
$ zca msg --help
.
# Help for a specific command
$ zca msg send --help
```

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

### Example SSE Event Payload

Source: https://zca-cli.dev/docs/index

Provides an example JSON payload for a Server-Sent Event. This illustrates the structure of data received when subscribing to real-time events.

```json
{
  "type": "message",
  "threadId": "123456789",
  "senderId": "987654321",
  "content": "Hello!",
  "timestamp": 1705847123456,
  "isGroup": false
}

```

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

### Real-time Listener

Source: https://zca-cli.dev/docs/index

Documentation for the `zca listen` command, which starts a persistent connection to Zalo's servers to receive messages in real-time.

```APIDOC
## Real-time Listener

**Overview:** The `listen` command starts a persistent connection to Zalo's servers, receiving messages as they arrive. This is perfect for building bots, webhooks, or automated responses.

**Command:** `zca listen`

**Usage:**
```bash
$ zca listen [options]
```

**Options:**

| Flag | Description | Default |
|---|---|---|
| `-e`, `--echo` | Echo received messages back to sender | — |
| `-p`, `--prefix <prefix>` | Only process messages starting with this prefix | — |
| `-w`, `--webhook <url>` | Forward messages to this URL | — |
| `-r`, `--raw` | Output raw JSON format | — |
| `-k`, `--keep-alive` | Auto-restart on disconnect | — |
| `--events <types>` | Filter event types (comma-separated). Options: message, reaction, undo, group_event, typing, seen, delivered, friend_event | — |
```

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

### Login QR Flow using Shell Commands

Source: https://zca-cli.dev/docs/index

This snippet demonstrates how to initiate and manage the QR code login flow using shell commands. It covers starting a login session, checking status, and aborting a session. The endpoints bypass authentication for initial QR generation.

```shell
# Start login for a profile (returns SSE stream)
$ curl -X POST http://localhost:56789/api/auth/login-qr \
$   -H 'Content-Type: application/json' \
$   -d '{"profile":"work"}'
.
# Multi-account: profile via URL path
$ curl -X POST http://localhost:56789/api/work/auth/login-qr
.
# Check active login sessions
$ curl http://localhost:56789/api/auth/login-qr/status
.
# Abort a login session
$ curl -X POST http://localhost:56789/api/auth/login-qr/abort \
$   -H 'Content-Type: application/json' \
$   -d '{"profile":"work"}'
```

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

### Get Support Code

Source: https://zca-cli.dev/docs/index

Display the device support code required for device-based license activation.

```APIDOC
## GET /license/support-code

### Description
Retrieves the device support code, which is necessary for device-based license activation.

### Method
GET

### Endpoint
/license/support-code

### Parameters
None

### Request Example
```
{
  "example": "$ zca license support-code"
}
```

### Response
#### Success Response (200)
- **support_code** (string) - The unique support code for the device.

#### Response Example
```
{
  "example": {
    "support_code": "ABC123XYZ789"
  }
}
```
```

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

### Interact with zca-cli Server using cURL

Source: https://zca-cli.dev/docs/index

Demonstrates how to interact with the zca-cli server using cURL commands. It shows examples for sending messages, retrieving profile information, listing friends, and listening for real-time events.

```bash
# Start the API server
$ zca serve
. 
# Send a text message
$ curl -X POST http://localhost:56789/api/messages/text \
$   -H 'Content-Type: application/json' \
$   -d '{"threadId":"USER_ID","message":"Hello from API!"}'
. 
# Get your profile
$ curl http://localhost:56789/api/me
. 
# List friends
$ curl http://localhost:56789/api/friends
. 
# Listen for real-time events (SSE)
$ curl -N http://localhost:56789/api/events

```

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

### Connect to Real-time Events using JavaScript

Source: https://zca-cli.dev/docs/index

Shows how to establish a connection to the Server-Sent Events (SSE) endpoint using JavaScript's EventSource API. It includes an example of handling incoming messages.

```javascript
$ const events = new EventSource("http://localhost:56789/api/events");
. 
$ events.onmessage = (event) => {
$   const data = JSON.parse(event.data);
$   console.log(data.type, data);
$   // Types: "connected", "message", "reaction", "group_event"
$ };

```

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

### Start Zalo REST API Server

Source: https://zca-cli.dev/docs/index

The `zca serve` command initiates a local REST API server that exposes all Zalo API functionality through 138 HTTP endpoints. This server supports real-time event streams via SSE, QR code login, multi-account serving, and includes authentication, rate limiting, and CORS.

```bash
$ zca serve [options]
```

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

### Sending Messages

Source: https://zca-cli.dev/docs/index

Example of sending a message using the `zca msg send` command, potentially with profile context.

```APIDOC
## Sending Messages

**Description:** Send messages using the `zca msg send` command. You can specify the profile using the `ZCA_PROFILE` environment variable.

**Usage:**
```bash
$ ZCA_PROFILE=<profile_name> zca msg send <thread_id> "<message>"
```

**Example:**
```bash
$ ZCA_PROFILE=work zca msg send 123456789 "Hello"
```
```

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

### Basic Zalo Listener Usage

Source: https://zca-cli.dev/docs/index

Start a basic Zalo listener to capture incoming messages. The output format provides sender information and message content. Press Ctrl+C to stop the listener. This is the simplest way to begin monitoring Zalo activity.

```bash
# Start basic listener
$ zca listen
.
# Output:
# [User] John Doe (123456789): Hello!
# [Group] Project Team (987654321) | Jane (111222333): Meeting at 3pm
```

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

### Zalo CLI Multi-Account API Server

Source: https://zca-cli.dev/docs/index

Shows how to serve multiple Zalo profiles from a single REST API server using the `--accounts` option. Each profile gets its own URL prefix for routing API requests and real-time events.

```bash
# Serve multiple profiles from one server
$ zca serve --accounts work,personal

# Each profile gets its own URL prefix:
# GET /api/work/friends    → work profile
# GET /api/personal/friends → personal profile
# GET /api/friends          → default (work)

# Example: Send from different accounts
$ curl -X POST http://localhost:56789/api/work/messages/text \
  -H 'Content-Type: application/json' \
  -d '{"threadId":"123","message":"From work"}'

$ curl -X POST http://localhost:56789/api/personal/messages/text \
  -H 'Content-Type: application/json' \
  -d '{"threadId":"456","message":"From personal"}'

# Real-time events are isolated per profile
$ curl -N http://localhost:56789/api/work/events     # work events only
$ curl -N http://localhost:56789/api/personal/events # personal events only

# Combine with auth: Add --auth-bearer or --auth-basic to protect all profiles.
# Example: zca serve --accounts work,personal --auth-bearer my-token
```

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

### Get Zalo Friend Recommendations

Source: https://zca-cli.dev/docs/index

Fetches friend recommendations based on your Zalo network. Supports outputting recommendations in JSON format using the --json flag.

```bash
$ zca friend recommendations [options]
```

```bash
$ zca friend recommendations --json
```

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

### Get zca-cli Support Code

Source: https://zca-cli.dev/docs/index

This command retrieves a unique support code for your device, which is necessary for device-based license activation. The code is used during the purchase process on the zca-cli website.

```shell
$ zca license support-code
```

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

### Zalo CLI Real-time Message Listener

Source: https://zca-cli.dev/docs/index

Details the `zca listen` command for starting a persistent connection to Zalo's servers to receive messages in real-time. It supports options for echoing messages, filtering by prefix, forwarding to webhooks, raw output, auto-restart, and filtering event types.

```bash
# Start the real-time message listener
$ zca listen [options]

# Example with options:
$ zca listen --echo --webhook https://example.com/webhook --events message,reaction --keep-alive
```

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

### Check Last Online Time (zca-cli)

Source: https://zca-cli.dev/docs/index

Checks and displays the last online time for a specified user ID. Includes an example.

```bash
$ zca me last-online <userId>
```

```bash
$ zca me last-online 123456789
```

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

### Get Friend Boards (zca-cli)

Source: https://zca-cli.dev/docs/index

Retrieves friend boards for a given conversation ID. Supports JSON output format.

```bash
$ zca friend boards <conversationId> [options]
```

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

### License Management API

Source: https://zca-cli.dev/docs/index

Manage your zca-cli license: get support codes, activate, check status, and deactivate. This section outlines the process for obtaining and activating device-based and account-based licenses.

```APIDOC
## License Management CLI Commands

### Get Support Code

#### Description
Generates a unique device support code required for device-based license activation.

#### Command
```bash
$ zca license support-code
```

### Get Zalo User ID

#### Description
Retrieves your Zalo User ID, which is required for account-based license activation.

#### Command
```bash
$ zca me id
```

### Activate License

#### Description
Activates your zca-cli license using the license key obtained after purchase.

#### Command
```bash
$ zca license activate <license_key>
```

### Check License Status

#### Description
Checks the current status of your zca-cli license.

#### Command
```bash
$ zca license status
```

### Deactivate License

#### Description
Deactivates your zca-cli license from the current device or account.

#### Command
```bash
$ zca license deactivate
```
```

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

### Update Profile Information (zca-cli)

Source: https://zca-cli.dev/docs/index

Updates the current user's profile information, such as name, gender, and birthday. Supports multiple options and includes examples.

```bash
$ zca me update [options]
```

```bash
$ zca me update --name "New Name"
```

```bash
$ zca me update --name "John" --birthday "1990-01-15"
```

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

### Get Zalo User ID (zca-cli)

Source: https://zca-cli.dev/docs/index

Retrieves the current user's unique Zalo user ID. Includes an example.

```bash
$ zca me id
```

```bash
$ zca me id
```

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

### Command Structure and Help

Source: https://zca-cli.dev/docs/index

Overview of the zca-cli command structure and how to access help.

```APIDOC
## Command Structure

zca-cli uses a hierarchical command structure:

```bash
$ zca [--profile <name>] <command-group> <command> [arguments] [options]
```

### Command Groups

- `auth`: Authentication
- `msg`: Messaging
- `group`: Group management
- `friend`: Friend management
- `me`: Profile/account
- `account`: Multi-account
- `listen`: Real-time events
- `license`: License management

## Getting Help

Use the `--help` flag to see available commands:

### General help
```bash
$ zca --help
```

### Help for a command group
```bash
$ zca msg --help
```

### Help for a specific command
```bash
$ zca msg send --help
```
```

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

### Multi-Account Serving

Source: https://zca-cli.dev/docs/index

Instructions on how to serve multiple Zalo profiles concurrently from a single server instance.

```APIDOC
## Multi-Account Serving

### Description

Serve multiple Zalo profiles from a single server instance. Each profile can be accessed via a URL prefix, allowing for isolated API interactions per profile. It is recommended to limit to 3-5 profiles per instance due to resource consumption.

### Method

N/A (Server configuration and URL routing)

### Endpoint

`/api/{profile}/endpoint` (profile-specific)
`/api/endpoint` (default profile)

### Parameters

#### Server Configuration

- **CLI Flag**: Use `--accounts <profile1>,<profile2>,...` to specify the profiles to serve.

#### URL Routing

- Requests to `/api/{profile}/...` are routed to the specified profile.
- Requests to `/api/...` (without a profile prefix) are routed to the first profile listed in the `--accounts` flag (the default profile).

#### SSE Events

- Each profile has its own isolated SSE stream. Connect to `/api/{profile}/events` for profile-specific events.

### Request Example

```bash
# Serve 'work' and 'personal' profiles
$ zca serve --accounts work,personal

# Access endpoints for the 'work' profile
$ curl http://localhost:56789/api/work/friends

# Access endpoints for the 'personal' profile
$ curl http://localhost:56789/api/personal/friends

# Access endpoints for the default profile ('work')
$ curl http://localhost:56789/api/friends

# List all loaded profiles
$ curl http://localhost:56789/api
```

### Response

N/A (Configuration and routing)

### Success Response (200)

N/A

### Response Example

N/A
```

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

### Activate zca-cli License with Key

Source: https://zca-cli.dev/docs/index

Activates the zca-cli with a provided license key. This is a core command for enabling the tool's features. Ensure you have a valid license key before execution.

```bash
$ zca license activate "YOUR_LICENSE_KEY_HERE"
```

```bash
$ zca license activate "eyJhbGciOiJFZDI1NTE5Ii..."
```

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

### Get Zalo User ID

Source: https://zca-cli.dev/docs/index

Retrieve your unique Zalo User ID, used for account-based license activation.

```APIDOC
## GET /me/id

### Description
Fetches the unique Zalo User ID associated with the currently logged-in Zalo account. This ID is used for account-based license activation.

### Method
GET

### Endpoint
/me/id

### Parameters
None

### Request Example
```
{
  "example": "$ zca me id"
}
```

### Response
#### Success Response (200)
- **user_id** (string) - The unique Zalo User ID.

#### Response Example
```
{
  "example": {
    "user_id": "1234567890123456789"
  }
}
```
```

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

### Serve Multiple Zalo Profiles and Access Endpoints

Source: https://zca-cli.dev/docs/index

Illustrates how to serve multiple Zalo profiles concurrently using the zca-cli. It shows how to access profile-specific endpoints using URL prefixes and how the default profile is handled.

```bash
# Serve two profiles
$ zca serve --accounts work,personal
. 
# Access work profile endpoints
$ curl http://localhost:56789/api/work/friends
. 
# Access personal profile endpoints
$ curl http://localhost:56789/api/personal/friends
. 
# Default profile (no prefix routes to first listed)
$ curl http://localhost:56789/api/friends  # routes to 'work'
. 
# List all loaded profiles
$ curl http://localhost:56789/api

```

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

### zca-cli command structure

Source: https://zca-cli.dev/docs/index

Illustrates the general syntax for executing zca-cli commands, including optional profile selection, command groups, commands, arguments, and options.

```shell
$ zca [--profile <name>] <command-group> <command> [arguments] [options]
```

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

### Change Profile Avatar (zca-cli)

Source: https://zca-cli.dev/docs/index

Changes the current user's profile avatar by specifying a file path. Includes an example.

```bash
$ zca me avatar <file>
```

```bash
$ zca me avatar ./photo.jpg
```

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

### Get Group Information using zca CLI

Source: https://zca-cli.dev/docs/index

Command to retrieve detailed information about a specific Zalo group. Requires the group ID.

```bash
$ zca group info <groupId>
$ zca group info 123456789
```

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

### Update Online Status (zca-cli)

Source: https://zca-cli.dev/docs/index

Updates the current user's online status (e.g., 'online', 'offline'). Includes examples for setting status.

```bash
$ zca me status <status>
```

```bash
$ zca me status online
```

```bash
$ zca me status offline
```

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

### Zca Serve Command Options

Source: https://zca-cli.dev/docs/index

Configuration options for the `zca serve` command to customize server behavior, including port, host, rate limiting, authentication, and account serving.

```APIDOC
## Zca Serve Command Options

### Description

Configure the Zalo CLI server with various options to control its network settings, security, and multi-account capabilities.

### Method

N/A (Command-line interface)

### Endpoint

N/A

### Parameters

#### CLI Flags

- **--port** (number) - Optional - Port to listen on. Default: 56789
- **--host** (string) - Optional - Host to bind to. Default: localhost
- **--rate-limit** (number) - Optional - Max requests per minute per IP. Set to 0 to disable. Default: 100
- **--max-sse** (number) - Optional - Max concurrent SSE connections. Set to 0 for unlimited. Default: 10
- **--auth-bearer** (string) - Optional - Require Bearer token authentication.
- **--auth-basic** (string) - Optional - Require Basic authentication in the format `user:pass`.
- **--accounts** (string) - Optional - Comma-separated profile names to serve.

### Request Example

```bash
# Start with defaults
$ zca serve

# Custom port and bearer token authentication
$ zca serve --port 8080 --auth-bearer mytoken

# Serve multiple accounts with basic auth
$ zca serve --accounts work,personal --auth-basic admin:password123
```

### Response

N/A (Command-line execution)

### Success Response (200)

N/A

### Response Example

N/A
```

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

### Login QR Flow using JavaScript and SSE

Source: https://zca-cli.dev/docs/index

This JavaScript function demonstrates how to handle the QR code login flow using Fetch API and Server-Sent Events (SSE). It connects to the login endpoint, reads SSE events, and updates the UI based on the event type (e.g., qr_generated, login_success).

```javascript
async function loginWithQR(profile = 'default') {
  const res = await fetch('http://localhost:56789/api/auth/login-qr', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile })
  });
.
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
.
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
.
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n\n');
    buffer = lines.pop();
.
    for (const line of lines) {
      if (!line.trim()) continue;
.
      const eventMatch = line.match(/^event: (.+)$/m);
      const dataMatch = line.match(/^data: (.+)$/m);
.
      if (eventMatch && dataMatch) {
        const event = eventMatch[1];
        const data = JSON.parse(dataMatch[1]);
.
        switch (event) {
          case 'qr_generated':
            displayQRCode(data.code); // Show QR to user
            break;
          case 'qr_scanned':
            showUserInfo(data.avatar, data.display_name);
            break;
          case 'login_success':
            redirectToDashboard();
            break;
          case 'login_error':
            showError(data.error);
            break;
        }
      }
    }
  }
}
```

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

### Get Zalo Group Invite Link Details

Source: https://zca-cli.dev/docs/index

Retrieves details about the current invite link for a Zalo group, such as its status or expiration. Requires the group ID.

```bash
$ zca group link-detail <groupId>
```

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

### Set Friend Alias (zca-cli)

Source: https://zca-cli.dev/docs/index

Sets or updates a nickname (alias) for a specified friend. Requires the user ID and the desired alias. Includes an example for setting an alias.

```bash
$ zca friend alias <userId> <alias>
```

```bash
$ zca friend alias 123456789 "Best Friend"
```

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

### License Activation

Source: https://zca-cli.dev/docs/index

Activate your Zalo CLI license using a provided license key.

```APIDOC
## POST /license/activate

### Description
Activates the Zalo CLI license on the current device using a license key.

### Method
POST

### Endpoint
/license/activate

### Parameters
#### Query Parameters
- **key** (string) - Required - The license key to activate.

### Request Example
```
{
  "example": "$ zca license activate \"YOUR_LICENSE_KEY_HERE\""
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of successful activation.

#### Response Example
```
{
  "example": {
    "message": "License activated successfully."
  }
}
```
```

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

### Multi-Account Login and Messaging (zca-cli)

Source: https://zca-cli.dev/docs/index

Demonstrates how to use the `--profile` flag to manage multiple Zalo accounts, including logging in and sending messages from different accounts. This showcases the multi-account support feature.

```bash
# Login to work account
$ zca --profile work auth login
.
# Send message from work account
$ zca --profile work msg send 123456789 "Hello from work"
.
# Login to personal account
$ zca --profile personal auth login
.
# Send from personal account
$ zca --profile personal msg send 987654321 "Hello from personal"
```

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

### Activate zca-cli license

Source: https://zca-cli.dev/docs/index

Activates your zca-cli license by first obtaining a device support code and then using it with your license key. This is a prerequisite for full functionality.

```shell
# Get your device support code
$ zca license support-code
.
# Activate with your license key
$ zca license activate "YOUR_LICENSE_KEY"
```

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

### Multi-Account API Server

Source: https://zca-cli.dev/docs/index

Instructions on how to serve multiple Zalo profiles from a single REST API server using the `--accounts` option.

```APIDOC
## Multi-Account API Server

**Description:** Serve multiple Zalo profiles from a single REST API server with the `--accounts` option. Each profile gets its own URL prefix for routing.

**Usage:**
```bash
$ zca serve --accounts <profile1>,<profile2>
```

**Example Workflow:**
```bash
# Serve multiple profiles from one server
$ zca serve --accounts work,personal

# Each profile gets its own URL prefix:
# GET /api/work/friends    → work profile
# GET /api/personal/friends → personal profile
# GET /api/friends          → default (work)

# Example: Send from different accounts
$ curl -X POST http://localhost:56789/api/work/messages/text \
  -H 'Content-Type: application/json' \
  -d '{"threadId":"123","message":"From work"}'

$ curl -X POST http://localhost:56789/api/personal/messages/text \
  -H 'Content-Type: application/json' \
  -d '{"threadId":"456","message":"From personal"}'

# Real-time events are isolated per profile
$ curl -N http://localhost:56789/api/work/events     # work events only
$ curl -N http://localhost:56789/api/personal/events # personal events only
```

**Security:** Combine with authentication using `--auth-bearer` or `--auth-basic`.
Example: `zca serve --accounts work,personal --auth-bearer my-token`
```

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

### Echo Mode for Zalo Messages

Source: https://zca-cli.dev/docs/index

Enable echo mode to automatically reply with the same message received. This is ideal for testing purposes. You can configure it to echo all messages or only those starting with a specific prefix, which will be stripped from the reply.

```bash
# Echo all messages
$ zca listen --echo
.
# Echo only messages starting with "!"
$ zca listen --echo --prefix "!"
```

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

### Activate zca-cli License

Source: https://zca-cli.dev/docs/index

This snippet shows the command to activate your zca-cli license using a license key obtained after purchase. This step is crucial for enabling full functionality of the tool.

```shell
# Example activation command (replace with actual command if provided)
# zca license activate YOUR_LICENSE_KEY
```

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

### Get Zalo User ID for zca-cli

Source: https://zca-cli.dev/docs/index

This command retrieves your Zalo User ID, which is required for account-based license activation. This license type allows usage across multiple devices linked to your Zalo account.

```shell
$ zca me id
```

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

### Multi-Account with Environment Variable (zca-cli)

Source: https://zca-cli.dev/docs/index

Shows how to use the `ZCA_PROFILE` environment variable to set the active Zalo account for subsequent commands, simplifying multi-account management.

```bash
# Set profile for current session
$ export ZCA_PROFILE=work
.
# All commands now use the work profile
$ zca msg send 123456789 "Hello"
$ zca group list
```

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

### Multi-Account Support

Source: https://zca-cli.dev/docs/index

Information on how to manage multiple Zalo accounts using profiles.

```APIDOC
## Using Profiles

### Method 1: `--profile` Flag
Use the `--profile` flag with any command to specify which profile to use.

### Usage Example
```bash
# Login to work account
$ zca --profile work auth login

# Send message from work account
$ zca --profile work msg send 123456789 "Hello from work"

# Login to personal account
$ zca --profile personal auth login

# Send from personal account
$ zca --profile personal msg send 987654321 "Hello from personal"
```

### Method 2: Environment Variable
Set the `ZCA_PROFILE` environment variable to specify the default profile for the current session.

### Usage Example
```bash
# Set profile for current session
$ export ZCA_PROFILE=work

# All commands now use the work profile
$ zca msg send 123456789 "Hello"
$ zca group list
```

### Profile Resolution Order
1. `--profile` CLI flag (highest priority)
2. `ZCA_PROFILE` environment variable
3. Default profile setting (set via account switch)
4. Falls back to "default" profile
```

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

### zca-cli License Key Formats

Source: https://zca-cli.dev/docs/index

Illustrates the two formats in which zca-cli license keys can be provided: a compact format with payload and signature separated by a dot, and a full JSON object.

```json
{
  "payload": "eyJwcm9kdWN0X2lkIjoiemNhLWNsaSI...",
  "signature": "..."
}
```

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

### Share Link with Zca

Source: https://zca-cli.dev/docs/index

Shares a URL link to a user or group.

```bash
$ zca msg link <threadId> <url> [options]
```

```bash
$ zca msg link 123456789 "https://github.com/user/repo"
```

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

### Authentication Commands

Source: https://zca-cli.dev/docs/index

Commands related to user authentication and session management.

```APIDOC
## GET /auth/status

### Description
Check the current login status and configuration location.

### Method
GET

### Endpoint
/auth/status

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
$ zca auth status
```

### Response
#### Success Response (200)
- **configLocation** (string) - The path to the configuration file.

#### Response Example
```json
{
  "configLocation": "/path/to/.zca/config"
}
```
```

```APIDOC
## POST /auth/login-creds

### Description
Re-authenticate using saved credentials without needing to scan a QR code again.

### Method
POST

### Endpoint
/auth/login-creds

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
$ zca auth login-creds
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful re-authentication.

#### Response Example
```json
{
  "message": "Successfully re-authenticated."
}
```
```

```APIDOC
## POST /auth/login

### Description
Initiate the login process, potentially requiring a QR code scan. If credentials are expired, this command should be run to get a fresh session.

### Method
POST

### Endpoint
/auth/login

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
$ zca auth login
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the login process has started or completed.

#### Response Example
```json
{
  "message": "Login process initiated. Please scan the QR code."
}
```
```

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

### Login QR via SSE

Source: https://zca-cli.dev/docs/index

Allows users to log in via QR code scan directly from your web/mobile app. The login flow streams real-time updates via SSE, from QR generation to successful authentication. These endpoints bypass authentication.

```APIDOC
## POST /api/auth/login-qr

### Description
Starts a login QR code flow and returns an SSE stream of real-time updates.

### Method
POST

### Endpoint
`/api/auth/login-qr`

### Parameters
#### Request Body
- **profile** (string) - Optional - The profile name to use for login. Defaults to 'default'.

### Request Example
```json
{
  "profile": "work"
}
```

### Response
#### Success Response (200)
- The response is an SSE stream with events like `qr_generated`, `qr_scanned`, `got_login_info`, `login_success`.

#### Response Example (SSE Stream)
```
event: qr_generated
data: {"code":"a_base64_encoded_qr_code"}

```

## POST /api/work/auth/login-qr

### Description
Starts a login QR code flow for a specific profile specified in the URL path.

### Method
POST

### Endpoint
`/api/{profile}/auth/login-qr`

### Parameters
#### Path Parameters
- **profile** (string) - Required - The profile name to use for login.

### Response
#### Success Response (200)
- The response is an SSE stream with events like `qr_generated`, `qr_scanned`, `got_login_info`, `login_success`.

## GET /api/auth/login-qr/status

### Description
Checks the status of active login sessions.

### Method
GET

### Endpoint
`/api/auth/login-qr/status`

### Response
#### Success Response (200)
- Returns a JSON object detailing the status of active login sessions.

## POST /api/auth/login-qr/abort

### Description
Aborts an active login session.

### Method
POST

### Endpoint
`/api/auth/login-qr/abort`

### Parameters
#### Request Body
- **profile** (string) - Required - The profile name of the session to abort.

### Request Example
```json
{
  "profile": "work"
}
```

### Response
#### Success Response (200)
- Indicates that the login session has been successfully aborted.

```

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

### Authentication

Source: https://zca-cli.dev/docs/index

Details on how to secure the API using Bearer token or HTTP Basic authentication.

```APIDOC
## Authentication

### Description

Protect your Zalo API with Bearer token or HTTP Basic authentication. Both methods utilize constant-time comparison for enhanced security against timing attacks.

### Method

N/A (Server configuration and request headers)

### Endpoint

All API endpoints

### Parameters

#### Bearer Token Authentication

- **Server Configuration**: Use the `--auth-bearer <token>` CLI flag when starting the server.
- **Request Header**: Include `Authorization: Bearer <your_token>` in your requests.

#### HTTP Basic Authentication

- **Server Configuration**: Use the `--auth-basic <user:pass>` CLI flag when starting the server.
- **Request Header**: Include `Authorization: Basic <base64_encoded_user:pass>` in your requests.

### Request Example

```bash
# Start server with Bearer token
$ zca serve --auth-bearer my-secret-token

# Authenticated request with Bearer token
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Bearer my-secret-token"

# Start server with Basic auth
$ zca serve --auth-basic admin:password123

# Authenticated request with Basic auth
$ curl http://localhost:56789/api/me \
$   -H "Authorization: Basic $(echo -n admin:password123 | base64)"
```

### Response

#### Error Response (401 Unauthorized)

Returned if authentication fails or is missing.

### Response Example

N/A
```

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

### Authentication API

Source: https://zca-cli.dev/docs/index

Manage your Zalo authentication with QR code login, credentials, and session management.

```APIDOC
## Authentication

Manage your Zalo authentication with QR code login, credentials, and session management.

### `zca auth login`

Login to Zalo by scanning a QR code with your Zalo mobile app.

#### Usage
```bash
$ zca auth login [options]
```

#### Options

| Flag | Description | Default |
|---|---|---|
| `-q`, `--qr-path <path>` | Save the QR code to a file | — |

#### Examples

Login with QR code in terminal:

```bash
$ zca auth login
```

Save QR code to a file:

```bash
$ zca auth login --qr-path ./qr.png
```

### `zca auth login-creds`

Login using previously saved credentials. Useful for re-authentication after restart.

#### Usage
```bash
$ zca auth login-creds
```

#### Examples

Re-authenticate with saved credentials:

```bash
$ zca auth login-creds
```

### `zca auth logout`

Logout and clear all saved credentials for the current profile.

#### Usage
```bash
$ zca auth logout
```

#### Examples

Logout from current profile:

```bash
$ zca auth logout
```

### `zca auth status`

Check authentication status and validate credentials.

#### Usage
```bash
$ zca auth status
```
```

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

### Login to Zalo using QR code

Source: https://zca-cli.dev/docs/index

Initiates the Zalo login process by displaying a QR code in the terminal. Users need to scan this code with their Zalo mobile app to authenticate.

```shell
$ zca auth login
```

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

### Account Management Commands

Source: https://zca-cli.dev/docs/index

Commands for listing, switching, adding, labeling, and removing Zalo account profiles.

```APIDOC
## Commands: Account Management

### `zca account list`

**Description:** Lists all account profiles with their status.

**Usage:**
```bash
$ zca account list
```

**Examples:**
```bash
$ zca account list
$ zca account ls
```

### `zca account switch <name>`

**Description:** Sets the default profile.

**Usage:**
```bash
$ zca account switch <name>
```

**Examples:**
```bash
$ zca account switch work
$ zca account use personal
```

### `zca account current`

**Description:** Shows the currently active profile.

**Usage:**
```bash
$ zca account current
```

**Examples:**
```bash
$ zca account current
$ zca account whoami
```

### `zca account add [name]`

**Description:** Creates a new profile and provides instructions for login.

**Usage:**
```bash
$ zca account add [name]
```

**Examples:**
```bash
$ zca account add work
$ zca account new
```

### `zca account label <name> <label>`

**Description:** Sets a description label for a profile.

**Usage:**
```bash
$ zca account label <name> <label>
```

**Examples:**
```bash
$ zca account label work "Office Zalo"
```

### `zca account remove <name>`

**Description:** Removes a profile and all its associated data.

**Usage:**
```bash
$ zca account remove <name>
```

**Examples:**
```bash
$ zca account remove old-account
$ zca account rm old-account
```

### Profile Name Rules

**Description:** Profile names should only contain letters, numbers, dashes, and underscores.

**Examples:** `work`, `personal-2`, `company_main`
```

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

### Parse Link Metadata using zca CLI

Source: https://zca-cli.dev/docs/index

Command to parse a URL and retrieve its metadata, such as title, description, and thumbnail. Requires the URL as input.

```bash
$ zca msg parse-link <url>
$ zca msg parse-link "https://github.com"
```

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

### Check zca-cli License Status

Source: https://zca-cli.dev/docs/index

Displays the current status and details of your zca-cli license. This command is useful for verifying if your license is active and to find its file path.

```bash
$ zca license status
```

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

### API Endpoints Overview

Source: https://zca-cli.dev/docs/index

Overview of the main API categories available through the Zalo CLI server, including messages, friends, groups, and real-time events.

```APIDOC
## API Endpoints Overview

### Description

Access the full interactive endpoint index at `http://localhost:56789/api`. Key categories include:

- **Messages**: 15 endpoints for sending text, images, videos, files, links, stickers, and cards.
- **Friends**: 14 endpoints for listing, searching, adding, blocking, and managing friend aliases.
- **Groups**: 25 endpoints for creating, managing members, settings, roles, and pins.
- **Conversations**: 18 endpoints for listing, pinning, hiding, muting, auto-deleting, and labeling conversations.
- **Polls**: 7 endpoints for creating, voting, locking, and sharing polls.
- **Auto-Replies**: 4 endpoints for CRUD operations on auto-reply rules with scheduling.
- **Settings**: 8 endpoints for managing privacy, online status, language, and labels.
- **Profile**: 5 endpoints for getting and updating profile information, avatar, and cover photo.

### Method

N/A (Endpoint categories)

### Endpoint

N/A

### Parameters

N/A

### Request Example

N/A

### Response

N/A

### Success Response (200)

N/A

### Response Example

N/A
```

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

### Zalo CLI Account Management Commands

Source: https://zca-cli.dev/docs/index

Provides commands to manage Zalo profiles, including listing, switching, adding, labeling, and removing accounts. These commands help in organizing and selecting different Zalo profiles for use.

```bash
$ zca account list
$ zca account ls
```

```bash
$ zca account switch <name>
$ zca account use personal
```

```bash
$ zca account add [name]
$ zca account new
```

```bash
$ zca account label <name> <label>
```

```bash
$ zca account remove <name>
$ zca account rm old-account
```

```bash
$ zca account current
$ zca account whoami
```

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

### List Friend Aliases (zca-cli)

Source: https://zca-cli.dev/docs/index

Lists all nicknames (aliases) set for friends. Supports JSON output format.

```bash
$ zca friend aliases [options]
```

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

### Zalo CLI Message Sending

Source: https://zca-cli.dev/docs/index

Demonstrates how to send messages using the Zalo CLI. It shows sending a message to a specific user ID with a given text content, and how to specify a profile using an environment variable.

```bash
# Send message using default profile
$ zca msg send 123456789 "Hello"

# Send message using a specific profile via environment variable
$ ZCA_PROFILE=work zca msg send 123456789 "Hello"
```

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

### Real-time Events (SSE)

Source: https://zca-cli.dev/docs/index

Connect to the `/api/events` endpoint to receive Server-Sent Events (SSE) in real-time for various Zalo activities.

```APIDOC
## Real-time Events (SSE)

### Description

Connect to the `/api/events` endpoint to receive Server-Sent Events (SSE) streamed in real-time as they occur. Supported event types include `connected`, `message`, `reaction`, and `group_event`.

### Method

GET

### Endpoint

`/api/events`

### Parameters

N/A

### Request Example

```javascript
const events = new EventSource("http://localhost:56789/api/events");

events.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data);
};
```

### Response

#### Success Response (200 OK)

Streams Server-Sent Events.

#### Response Example

```json
{
  "type": "message",
  "threadId": "123456789",
  "senderId": "987654321",
  "content": "Hello!",
  "timestamp": 1705847123456,
  "isGroup": false
}
```
```

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

### List Avatars (zca-cli)

Source: https://zca-cli.dev/docs/index

Lists all available profile avatars for the current user. Supports JSON output format.

```bash
$ zca me avatars [options]
```