> For the complete documentation index, see [llms.txt](https://docs.mongenscave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mongenscave.com/premium-products/discordlink/feature-help/bot-settings.md).

# Bot Settings

## 🔧 Custom Discord Bot Presence

The `bot-settings` section in the `config.yml` allows you to customize the **activity** and **online status** of the Discord bot managed by the plugin.

This feature supports **PlaceholderAPI placeholders**, enabling dynamic values such as total player count across servers (e.g. `%bungee_total%`).

⚠️ Multi-Server Support Notice

If you run this plugin on **multiple Minecraft servers (multi-server setup)** with the same Discord bot token, you **must enable `bot-settings.enabled: true` on only ONE server**.\
Having this enabled on more than one server **may result in duplicate status updates or Discord rate-limiting**.

## 📁 Configuration

Add or edit the following section in your `config.yml`:

```yaml
discord:
  token: "your-discord-bot-token"
  guild-id: "your-guild-id"

  bot-settings:
    # ⚠️ ENABLE WITH CAUTION!
    # Only one server should manage bot presence if you're running multiple servers.
    enabled: true

    # The text to display as the bot's activity.
    # PlaceholderAPI placeholders (e.g. %bungee_total%) are supported.
    activity: "Playing with %bungee_total% players"

    # The type of activity:
    # Options: PLAYING, WATCHING, LISTENING, COMPETING
    activity-type: "PLAYING"

    # The bot's online status:
    # Options: ONLINE, IDLE, DND, INVISIBLE
    status: "ONLINE"

  change-nickname: true
  restrict-to-channel: true
  target-channel-id: "your-channel-id"
```

## 🔁 Live Updating with Placeholders

If `activity` contains **PlaceholderAPI placeholders**, they are parsed automatically using your installed placeholder expansions.

#### 🔄 Refresh Frequency:

* The activity text is refreshed:
  * **60 ticks** after startup (3 seconds)
  * **every 3 minutes** afterwards (asynchronously)
* No update is sent unless the placeholder-resolved text has changed, avoiding unnecessary API calls.

## 🔍 Example Output

If you use the following:

```yaml
activity: "Playing with %bungee_total% players"
activity-type: "PLAYING"
status: "ONLINE"
```

Your bot will display:

> **Playing with 124 players**

And its status will appear as **Online**.