> For the complete documentation index, see [llms.txt](https://docs.ragnasync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ragnasync.com/getting-started/channels-conf.md).

# Channels Config

The `channels.conf` file configures the in-game channel system and RagnaSync integration settings. This file is located in your rAthena server's `conf/channels.conf`.

## RagnaSync Discord Integration

The `discord` block contains all RagnaSync-specific settings for connecting your Ragnarok server to Discord.

### Connection Settings

Core settings for connecting to the RagnaSync service.

```conf
discord: {
    // RagnaSync Service Host
    ragnasync_host_name: "ragnasync.com"

    // Discord Server Settings
    ragnasync_discord_id: "123456789012345678"
    ragnasync_discord_guid: "a1b2c3d4e5f6789012345678abcdef00"

    // Ragnarok Server Client Settings
    ragnasync_client_guid: "f0e1d2c3b4a5678901234567fedcba99"

    // Connection Settings
    ragnasync_enabled: true
    ragnasync_retry_first: 300
    ragnasync_retry_delay: 1800
    ragnasync_retry_max: 3
}
```

| Setting                  | Type   | Default           | Description                                                                         |
| ------------------------ | ------ | ----------------- | ----------------------------------------------------------------------------------- |
| `ragnasync_host_name`    | string | `"ragnasync.com"` | RagnaSync service hostname                                                          |
| `ragnasync_discord_id`   | string | `""`              | Discord server ID (17-19 digit snowflake)                                           |
| `ragnasync_discord_guid` | string | `""`              | Discord server security key (32 hex chars, issued with your `ragnasync_discord_id`) |
| `ragnasync_client_guid`  | string | `""`              | Ragnarok client security key (32 hex chars, from dashboard)                         |
| `ragnasync_enabled`      | bool   | `true`            | Auto-connect when server starts                                                     |
| `ragnasync_retry_first`  | int    | `300`             | First retry delay in seconds (5 minutes)                                            |
| `ragnasync_retry_delay`  | int    | `1800`            | Delay between subsequent retries (30 minutes)                                       |
| `ragnasync_retry_max`    | int    | `3`               | Maximum retry attempts (0 = unlimited)                                              |

{% hint style="warning" %}
**The retry defaults decide how long your relay stays down.**

If the connection drops — a network blip, or RagnaSync restarting for an update — your server waits `ragnasync_retry_first` seconds before its **first** reconnect attempt. At the default of `300` that is a full five minutes with no chat relay in either direction, even though the service is back within seconds.

If that first attempt misses, the next one is `ragnasync_retry_delay` away — another **30 minutes** by default.

Lowering the first retry costs nothing and closes most of that gap:

```
ragnasync_retry_first: 20      // try again after 20s instead of 5 minutes
ragnasync_retry_delay: 120     // and every 2 minutes after that
ragnasync_retry_max: 0         // keep trying indefinitely
```

Both values are read from this file when your server starts, so a restart of your Ragnarok server is all that is needed — no recompile. Avoid going below \~10 seconds: very aggressive retries add load without reconnecting meaningfully faster.
{% endhint %}

***

### @Command Logging

Log GM commands to a Discord channel for moderation and audit purposes.

```conf
ragnasync_at_command_log_enabled: true
ragnasync_at_command_log_channel_id: "123456789012345678"
ragnasync_at_command_log_group_min: 1
ragnasync_at_command_log_group_max: 99
```

| Setting                               | Type   | Default | Description                         |
| ------------------------------------- | ------ | ------- | ----------------------------------- |
| `ragnasync_at_command_log_enabled`    | bool   | `false` | Enable @command logging             |
| `ragnasync_at_command_log_channel_id` | string | `""`    | Discord channel ID for command logs |
| `ragnasync_at_command_log_group_min`  | int    | `1`     | Minimum GM group level to log       |
| `ragnasync_at_command_log_group_max`  | int    | `99`    | Maximum GM group level to log       |

**Tip:** Set `group_min: 99` to only log admin commands, or `group_min: 1` to log all staff.

***

### Mob Item Drop Logging

Log rare item drops from monsters to Discord.

```conf
ragnasync_mob_item_drop_log_enabled: true
ragnasync_mob_item_drop_log_channel_id: "123456789012345678"
ragnasync_mob_item_drop_log_min_rate: 100
ragnasync_mob_item_drop_log_types: "card,weapon,armor"
```

| Setting                                  | Type   | Default | Description                                                      |
| ---------------------------------------- | ------ | ------- | ---------------------------------------------------------------- |
| `ragnasync_mob_item_drop_log_enabled`    | bool   | `false` | Enable drop logging                                              |
| `ragnasync_mob_item_drop_log_channel_id` | string | `""`    | Discord channel for drop logs                                    |
| `ragnasync_mob_item_drop_log_min_rate`   | int    | `500`   | Minimum rate to log (see drop rates below)                       |
| `ragnasync_mob_item_drop_log_types`      | string | `"all"` | Item categories to log (see [Item Drop Types](#item-drop-types)) |

**Drop Rate Values:**

| Value   | Rate |
| ------- | ---- |
| `10000` | 100% |
| `1000`  | 10%  |
| `500`   | 5%   |
| `100`   | 1%   |
| `10`    | 0.1% |

***

### Homunculus Item Drop Logging

Log item drops from Homunculus kills.

```conf
ragnasync_hom_item_drop_log_enabled: true
ragnasync_hom_item_drop_log_channel_id: "123456789012345678"
ragnasync_hom_item_drop_log_min_rate: 500
ragnasync_hom_item_drop_log_types: "all"
```

| Setting                                  | Type   | Default | Description                                                      |
| ---------------------------------------- | ------ | ------- | ---------------------------------------------------------------- |
| `ragnasync_hom_item_drop_log_enabled`    | bool   | `false` | Enable drop logging                                              |
| `ragnasync_hom_item_drop_log_channel_id` | string | `""`    | Discord channel for drop logs                                    |
| `ragnasync_hom_item_drop_log_min_rate`   | int    | `500`   | Minimum rate to log                                              |
| `ragnasync_hom_item_drop_log_types`      | string | `"all"` | Item categories to log (see [Item Drop Types](#item-drop-types)) |

***

### Mercenary Item Drop Logging

Log item drops from Mercenary kills.

```conf
ragnasync_merc_item_drop_log_enabled: true
ragnasync_merc_item_drop_log_channel_id: "123456789012345678"
ragnasync_merc_item_drop_log_min_rate: 500
ragnasync_merc_item_drop_log_types: "all"
```

| Setting                                   | Type   | Default | Description                                                      |
| ----------------------------------------- | ------ | ------- | ---------------------------------------------------------------- |
| `ragnasync_merc_item_drop_log_enabled`    | bool   | `false` | Enable drop logging                                              |
| `ragnasync_merc_item_drop_log_channel_id` | string | `""`    | Discord channel for drop logs                                    |
| `ragnasync_merc_item_drop_log_min_rate`   | int    | `500`   | Minimum rate to log                                              |
| `ragnasync_merc_item_drop_log_types`      | string | `"all"` | Item categories to log (see [Item Drop Types](#item-drop-types)) |

***

### Mob Death Logging

Log when specific mob types are killed (MVP, Mini-boss, or normal mobs).

```conf
ragnasync_mob_death_log_enabled: true
ragnasync_mob_death_log_channel_id: "123456789012345678"
ragnasync_mob_death_log_types: "mvp,miniboss"
```

| Setting                              | Type   | Default | Description                                                  |
| ------------------------------------ | ------ | ------- | ------------------------------------------------------------ |
| `ragnasync_mob_death_log_enabled`    | bool   | `false` | Enable death logging                                         |
| `ragnasync_mob_death_log_channel_id` | string | `""`    | Discord channel for death logs                               |
| `ragnasync_mob_death_log_types`      | string | `"all"` | Mob classes to log (see [Mob Death Types](#mob-death-types)) |

***

### Container Logging

Log when players open containers like Card Albums and Gift Boxes.

```conf
ragnasync_container_log_enabled: true
ragnasync_container_log_channel_id: "123456789012345678"
ragnasync_container_log_types: "card_album,giftbox"
ragnasync_container_log_group_min: 0
ragnasync_container_log_group_max: 0
```

| Setting                              | Type   | Default | Description                                                      |
| ------------------------------------ | ------ | ------- | ---------------------------------------------------------------- |
| `ragnasync_container_log_enabled`    | bool   | `false` | Enable container logging                                         |
| `ragnasync_container_log_channel_id` | string | `""`    | Discord channel for container logs                               |
| `ragnasync_container_log_types`      | string | `"all"` | Container types to log (see [Container Types](#container-types)) |
| `ragnasync_container_log_group_min`  | int    | `0`     | Minimum GM group level to log                                    |
| `ragnasync_container_log_group_max`  | int    | `99`    | Maximum GM group level to log                                    |

**Tip:** Set `group_min: 0` and `group_max: 0` to only log regular players (no GMs).

***

### Shop Logging

Log NPC shop buy/sell transactions.

```conf
ragnasync_shop_log_enabled: true
ragnasync_shop_log_channel_id: "123456789012345678"
ragnasync_shop_log_buy_enabled: true
ragnasync_shop_log_sell_enabled: true
ragnasync_shop_log_min_zeny: 1000000
ragnasync_shop_log_group_min: 0
ragnasync_shop_log_group_max: 0
```

| Setting                           | Type   | Default | Description                       |
| --------------------------------- | ------ | ------- | --------------------------------- |
| `ragnasync_shop_log_enabled`      | bool   | `false` | Enable NPC shop logging           |
| `ragnasync_shop_log_channel_id`   | string | `""`    | Discord channel for shop logs     |
| `ragnasync_shop_log_buy_enabled`  | bool   | `true`  | Log buy transactions              |
| `ragnasync_shop_log_sell_enabled` | bool   | `true`  | Log sell transactions             |
| `ragnasync_shop_log_min_zeny`     | int    | `0`     | Minimum zeny to log (0 = log all) |
| `ragnasync_shop_log_group_min`    | int    | `0`     | Minimum GM group level to log     |
| `ragnasync_shop_log_group_max`    | int    | `99`    | Maximum GM group level to log     |

***

### Vending Logging

Log player-to-player vending transactions and shop openings.

```conf
ragnasync_vending_log_enabled: true
ragnasync_vending_log_channel_id: "123456789012345678"
ragnasync_vending_log_min_zeny: 100000
ragnasync_vending_log_group_min: 0
ragnasync_vending_log_group_max: 99
```

| Setting                            | Type   | Default | Description                       |
| ---------------------------------- | ------ | ------- | --------------------------------- |
| `ragnasync_vending_log_enabled`    | bool   | `false` | Enable vending logging            |
| `ragnasync_vending_log_channel_id` | string | `""`    | Discord channel for vending logs  |
| `ragnasync_vending_log_min_zeny`   | int    | `0`     | Minimum zeny to log (0 = log all) |
| `ragnasync_vending_log_group_min`  | int    | `0`     | Minimum GM group level to log     |
| `ragnasync_vending_log_group_max`  | int    | `99`    | Maximum GM group level to log     |

**Note:** This setting also controls `vending_item` messages sent when a player opens their shop.

***

### Refine Logging

Log equipment refining attempts (success/failure/downgrade).

```conf
ragnasync_refine_log_enabled: true
ragnasync_refine_log_channel_id: "123456789012345678"
ragnasync_refine_log_min_level: 7
ragnasync_refine_log_group_min: 0
ragnasync_refine_log_group_max: 0
```

| Setting                           | Type   | Default | Description                               |
| --------------------------------- | ------ | ------- | ----------------------------------------- |
| `ragnasync_refine_log_enabled`    | bool   | `false` | Enable refine logging                     |
| `ragnasync_refine_log_channel_id` | string | `""`    | Discord channel for refine logs           |
| `ragnasync_refine_log_min_level`  | int    | `0`     | Minimum refine level to log (0 = log all) |
| `ragnasync_refine_log_group_min`  | int    | `0`     | Minimum GM group level to log             |
| `ragnasync_refine_log_group_max`  | int    | `99`    | Maximum GM group level to log             |

**Tip:** Set `min_level: 7` to only log high-refine attempts where things get exciting!

***

### Population Logging

Send periodic server population statistics to Discord.

```conf
ragnasync_population_log_enabled: true
ragnasync_population_log_channel_id: "123456789012345678"
ragnasync_population_log_interval: 1800
```

| Setting                               | Type   | Default | Description                         |
| ------------------------------------- | ------ | ------- | ----------------------------------- |
| `ragnasync_population_log_enabled`    | bool   | `false` | Enable population stats             |
| `ragnasync_population_log_channel_id` | string | `""`    | Discord channel for population logs |
| `ragnasync_population_log_interval`   | int    | `3600`  | Update interval in seconds (min 60) |

***

### Ticket Support System

Enable player support tickets via PM @Support or @request command.

```conf
ragnasync_ticket_support_system_enabled: true
ragnasync_ticket_support_system_close_on_logout: true
```

| Setting                                           | Type | Default | Description                            |
| ------------------------------------------------- | ---- | ------- | -------------------------------------- |
| `ragnasync_ticket_support_system_enabled`         | bool | `false` | Enable ticket support system           |
| `ragnasync_ticket_support_system_close_on_logout` | bool | `false` | Auto-close ticket when player logs out |

***

## Log Type Filters

The `*_log_types` keys all take a **comma-separated, case-insensitive** list of tokens. Common behavior across every filter:

* `all` (or an empty string) disables the filter — everything is logged.
* Unknown tokens are skipped with a `[Warning]: Unknown ... type '...'` line printed at map-server startup.
* If every token in your list is invalid, the mask is empty — which currently falls back to "log everything." If your filter isn't doing anything, check the map-server startup log first.

Each filter key accepts a **different** set of tokens. Mixing them up is the most common configuration mistake: for example, `ragnasync_mob_item_drop_log_types` is filtered by **item** category, not by the class of mob that dropped it, so `"mvp,miniboss"` is silently invalid and logs nothing specific.

### Item Drop Types

Used by `ragnasync_mob_item_drop_log_types`, `ragnasync_hom_item_drop_log_types`, and `ragnasync_merc_item_drop_log_types`. Filters which **item categories** are announced when a monster drops them.

| Token        | Filters drops of                     |
| ------------ | ------------------------------------ |
| `all`        | Every item category (default)        |
| `healing`    | Healing items (potions, herbs, food) |
| `usable`     | Consumables / usable items           |
| `etc`        | Miscellaneous / crafting materials   |
| `armor`      | Armor pieces                         |
| `weapon`     | Weapons                              |
| `card`       | Monster cards                        |
| `petegg`     | Pet eggs                             |
| `petarmor`   | Pet equipment                        |
| `ammo`       | Arrows, bullets, other ammunition    |
| `shadowgear` | Shadow equipment                     |
| `cash`       | Cash shop items                      |

{% hint style="warning" %}
There is currently no way to filter item-drop logs by the **mob class** that dropped the item (e.g. "only log drops from MVPs"). A value like `"mvp,miniboss"` here will be rejected and log nothing — use `min_rate` to narrow drops, or route messages through the dashboard if you need MVP-specific alerts.
{% endhint %}

### Mob Death Types

Used by `ragnasync_mob_death_log_types`. Filters which **mob classes** fire a death log when killed.

| Token      | Filters kills of                            |
| ---------- | ------------------------------------------- |
| `all`      | Every mob class (default)                   |
| `normal`   | Regular mobs — logs every kill, very spammy |
| `miniboss` | Mini-boss monsters                          |
| `mvp`      | MVPs                                        |

### Container Types

Used by `ragnasync_container_log_types`. Filters which container items fire a log when opened.

| Token        | Filters openings of                        |
| ------------ | ------------------------------------------ |
| `all`        | Every container type (default)             |
| `card_album` | Card Albums (Old Card Album, variants)     |
| `giftbox`    | Gift boxes (note: one word, no underscore) |
| `misc_box`   | Other miscellaneous container items        |

***

## Channel Discord Linking

Any in-game channel can be linked to Discord by adding the `discord_channel_id` property to its configuration.

### Public Channel Example

```conf
{
    name: "#global"
    alias: "[Global]"
    color: "White"
    type: "CHAN_TYPE_PUBLIC"
    delay: 1000
    autojoin: true
    leave: false
    chat: true
    discord_channel_id: "123456789012345678"  // Link to Discord channel
}
```

### Private Channel Default

Private channels can also have a default Discord link:

```conf
private_channel: {
    allow: true
    color: "Default"
    delay: 1000
    max_member: 1000
    discord_channel_id: "123456789012345678"  // Default Discord channel
}
```

**Notes:**

* Only channels with `discord_channel_id` configured will send/receive Discord messages
* Messages from in-game appear in Discord and vice versa

***

## Channel Types

| Type               | Description                   |
| ------------------ | ----------------------------- |
| `CHAN_TYPE_PUBLIC` | Open channels anyone can join |
| `CHAN_TYPE_ALLY`   | Guild alliance channels       |
| `CHAN_TYPE_MAP`    | Map-specific local channels   |

***

## Available Colors

```conf
colors: {
    Default: "0xffffff"
    Red: "0xff0000"
    Blue: "0x83cfe9"
    Orange: "0xe57c00"
    Cyan: "0x00b89d"
    Yellow: "0xffff90"
    Green: "0x28bf00"
    White: "0xFFFFFF"
    Purple: "0xD67FFF"
    LightGreen: "0xB6FF00"
    Normal: "0x00ff00"
}
```

***

## GM Commands

These in-game commands allow GMs to manage the RagnaSync service connection.

### @startsync

Starts the RagnaSync service if it was stopped.

```
@startsync
```

**Notes:**

* Reloads configuration from `channels.conf` before connecting
* Resets retry counter
* No effect if service is already running

### @stopsync

Stops the RagnaSync service and disconnects from the server.

```
@stopsync
```

**Notes:**

* Gracefully disconnects from RagnaSync
* Service will not auto-reconnect until manually started
* Useful for maintenance or debugging

### @reloadsync

Reloads the RagnaSync configuration and reconnects to the service.

```
@reloadsync
```

**Aliases:** `@syncreload`

**Notes:**

* Reads fresh settings from `channels.conf`
* Reconnects with new configuration
* Use after modifying any RagnaSync settings
* Displays current retry settings after reload

### @syncstatus

Displays the current RagnaSync connection status.

```
@syncstatus
```

**Output includes:**

* Connection state (connected/disconnected/stopped)
* Retry attempt count (if applicable)
* Current configuration summary

***

## Getting Your Discord IDs

See [Installation](/getting-started/installation.md) for instructions on obtaining your Discord Server ID and Channel IDs.

The `ragnasync_discord_guid` and `ragnasync_client_guid` are provided by RagnaSync during installation.

{% hint style="warning" %}
`ragnasync_discord_id` and `ragnasync_discord_guid` are a matched pair — the GUID belongs to that one Discord server. Your server is turned away at connect time if they don't match, so if you move to a different Discord server, ask support to reissue **both** together. Copying a `channels.conf` from another server won't work for the same reason.
{% endhint %}

***

## Using conf/import/channels.txt

{% hint style="info" %}
**Running multiple environments?** This section is for you.
{% endhint %}

If you run both a live server and a test server from the same codebase, you'll want each environment to have its own `ragnasync_client_guid`. The problem is that `conf/channels.conf` is typically committed to git — so any GUID you set there gets shared across all environments.

The solution: use `conf/import/channels.txt` instead.

### Why channels.txt?

| File                       | Git tracked?    | Best for                                                        |
| -------------------------- | --------------- | --------------------------------------------------------------- |
| `conf/channels.conf`       | Yes (committed) | Shared settings like channel colors, types, Discord channel IDs |
| `conf/import/channels.txt` | No (gitignored) | Per-environment settings like `ragnasync_client_guid`           |

Most rAthena and Hercules setups gitignore the `conf/import/` folder by default. This makes it the perfect place for settings that differ between your live and test servers.

### How to set it up

Create or edit `conf/import/channels.txt` on each server and add your environment-specific GUID:

```conf
ragnasync_client_guid: "your-unique-guid-here"
```

That's it! Settings in `conf/import/channels.txt` override anything in `conf/channels.conf`, so each environment gets its own identity on RagnaSync.

### Example: Live + Test setup

**Live server** (`conf/import/channels.txt`):

```conf
ragnasync_client_guid: "a1b2c3d4e5f6789012345678abcdef00"
```

**Test server** (`conf/import/channels.txt`):

```conf
ragnasync_client_guid: "f0e1d2c3b4a5678901234567fedcba99"
```

Each server now has its own dashboard, crash logs, metrics, and status tracking on RagnaSync — completely independent.

{% hint style="success" %}
**Tip:** You can leave `ragnasync_client_guid` empty in `conf/channels.conf` and only set it in `conf/import/channels.txt` on each server. A GUID is generated automatically on first connect if you don't set one.
{% endhint %}