> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancestraldev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord Bot Integration & Setup

> Complete setup and command guide for the Avalex Discord Bot integration.

# Discord Bot Integration & Setup

Avalex includes a built-in **Discord Bot** powered by Discord4J that connects directly to your licensing server and MongoDB database.

The Discord Bot allows your community members and customers to view their active licenses directly inside Discord, and allows administrators to issue new licenses and create order records on the fly using native Discord Slash Commands and interactive modals.

***

## Key Features

* **`/my-licenses`**: End-users can securely view all software licenses linked to their Discord account in a private (ephemeral) embed showing license keys, product names, expiration dates, and IP/HWID slot usages.
* **`/issue-license`**: Server administrators can instantly grant a license to any Discord member. Opens an interactive popup modal to specify custom keys, expiration days, slot limits, and order amounts.
* **Auto Customer Creation**: Issuing a license to a new Discord user automatically creates a Customer profile in your Avalex database with their Discord ID and username.
* **Full Audit Logging**: All license issuances via Discord are logged to the administrative audit log (`license_issued_via_discord`).

***

## 1. Create Your Discord Bot in Discord Developer Portal

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
2. Click **New Application**, enter a name (e.g. `Avalex Licensing`), and click **Create**.
3. In the left sidebar, navigate to **Bot**:
   * Click **Reset Token** (or **Copy Token**) to copy your Bot Token. Keep this private!
   * Under **Privileged Gateway Intents**, enable:
     * **Server Members Intent**
     * **Message Content Intent**
   * Click **Save Changes**.
4. In the left sidebar, navigate to **OAuth2 > URL Generator**:
   * Under **Scopes**, select:
     * `bot`
     * `applications.commands`
   * Under **Bot Permissions**, select:
     * `Administrator` (or `Send Messages`, `Embed Links`, `Use Slash Commands`).
   * Copy the generated URL at the bottom and open it in your browser to invite the bot to your Discord server.

***

## 2. Configure Avalex Server

Enable the Discord bot in your `application.conf` or by passing environment variables:

### Option A: Environment Variables (Recommended)

```bash theme={null}
export DISCORD_BOT_ENABLED=true
export DISCORD_BOT_TOKEN="YOUR_DISCORD_BOT_TOKEN_HERE"
```

### Option B: `application.conf`

```hocon theme={null}
discord {
  enabled = true
  token = "YOUR_DISCORD_BOT_TOKEN_HERE"
}
```

When you start your Avalex server, the bot will automatically connect to Discord Gateway and register slash commands globally and to all connected guilds:

```text theme={null}
[DiscordBot] Connected as Avalex#1234
```

***

## 3. Bot Slash Commands Reference

### 1. `/my-licenses`

Allows any customer or Discord server member to check their active licenses.

* **Permissions**: Available to everyone (`@everyone`).
* **Visibility**: **Ephemeral** (only visible to the user running the command).
* **Matching Logic**: Queries the Avalex database for Customer profiles where `socials.DiscordID` or `socials.Discord` matches the user's Discord ID.
* **Embed Information Displayed**:
  * License Key ID (e.g. `ABCD-EFGH-IJKL-MNOP`)
  * Status: `🟢 Active` or `🔴 Disabled`
  * Product Name & Product ID
  * Expiry Date (formatted Discord timestamp `<t:...:R>` or `Never (Lifetime)`)
  * IP Usage: `Current / Max` (e.g. `1 / 2` or `1 / ∞`)
  * HWID Usage: `Current / Max` (e.g. `1 / 1` or `1 / ∞`)

***

### 2. `/issue-license`

Allows server administrators to issue a new license directly inside Discord.

* **Permissions**: **Server Administrator Only** (`Permission.ADMINISTRATOR`).
* **Command Arguments**:
  * `user` *(Required, User)*: The Discord member receiving the license.
  * `product` *(Required, String)*: Product ID or Name.
  * `order` *(Optional, Boolean)*: `true` to record a corresponding Order record, `false` otherwise.

#### Interactive Popup Modal:

When run, the bot opens an interactive modal with the following fields:

| Field | Description | Default / Fallback |
| :- | :- | :- |
| **Custom License Key** | Specific license key string | Auto-generates using configured `license.format` pattern |
| **Expiry in Days** | License duration in days (e.g. `30`) | Blank = Lifetime (Never expires) |
| **Max IPs** | Allowed IP activations | Product default (or unlimited `∞`) |
| **Max HWIDs** | Allowed HWID activations | Product default (or unlimited `∞`) |
| **Order Price** | Total price for the order record | Product default price (e.g. `$29.99`) |

#### What Happens on Submission:

1. If the Discord user does not exist in the Avalex Customer database, a new Customer profile is automatically created.
2. The license is created in MongoDB with the specified parameters.
3. If an order was requested, an Order record is created and linked to the Customer and License.
4. An audit log entry is recorded: `license_issued_via_discord` performed by `discord:<admin_id>`.
5. An embed is displayed to the admin confirming all license details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.