Wolvesville Discord Bot

English · Tiếng Việt

A self-hosted Discord bot that uses slash commands to retrieve data from the official Wolvesville Public API. Each operator hosts their own instance with their own Discord token and Wolvesville API key.

This project uses official lookup and integration endpoints, with clan commands intentionally limited to read-only operations.

Commands

• /wov-player username — find a player by exact username.
• /wov-highscores period [limit] — view daily, weekly, monthly, or all-time XP leaders.
• /wov-roles [query] [team] [locale] — search and filter roles.
• /wov-rotation [mode] [locale] — view the current role rotations.
• /wov-ranked view [language] — view the current ranked season or leaderboard.
• /clan search name [exact] — search for a clan.
• /clan authorized — list clans that added the Wolvesville bot and granted permissions.
• /clan info clan-id — view clan information.
• /clan members clan-id — view clan members.
• /clan quest clan-id — view the active clan quest (read-only).

Requirements

• Node.js 20.11 or newer; the current LTS release is recommended.
• A Discord application with a bot user.
• A Wolvesville Public API key.
• A computer or server that can keep a Node.js process running.

1. Get a Wolvesville API key

Follow the official Wolvesville instructions:

1. Sign in to the Wolvesville account that will own the API bot and key.
2. Open Settings in Wolvesville.
3. Select Wolvesville public API.
4. Create an API bot if the account does not already have one. Each Wolvesville account can create only one API bot.
5. Copy the security key / API key and store it securely.

The screen shows two different values:

• API key / security key authenticates API requests as Authorization: Bot <apiKey>. It is secret and belongs in WOLVESVILLE_API_KEY in your .env file.
• Bot ID does not authenticate requests. A clan leader only needs this ID to add the bot as a clan bot and grant access to private clan data.

Never post your API key on GitHub or Discord, include it in screenshots, or expose it in public logs. If it is leaked, reset the security key in Wolvesville and update your .env file.

Official resources:

• Wolvesville Public API documentation
• OpenAPI specification
• Wolvesville Terms of Service
• API base URL: https://api.wolvesville.com

2. Create a Discord bot

1. Open the Discord Developer Portal and select New Application.
2. Open the Bot page, create the bot user if prompted, and copy or reset its token.
3. Save the token as DISCORD_TOKEN. Never share it or commit it to Git.
4. Under General Information, copy the Application ID into DISCORD_CLIENT_ID.
5. For testing in one server, enable Developer Mode in Discord, right-click the server, select Copy Server ID, and save it as DISCORD_GUILD_ID.
6. In the OAuth2/Installation settings, configure a Guild Install with the bot and applications.commands scopes.
7. Grant only the required bot permissions: View Channels, Send Messages, and Embed Links. The bot does not need Administrator or Message Content Intent.
8. Use the install link generated by Discord to add the bot to your server.

DISCORD_GUILD_ID is optional. When set, commands are registered to that test server and update almost immediately. When omitted, commands are registered globally and may take some time to appear in every server.

3. Install the project

Clone the repository and install its dependencies:

git clone https://github.com/xVanDat/Wolvesville-Discord-Bot.git
cd Wolvesville-Discord-Bot
npm install

Create .env from the example file:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Enter your own credentials:

DISCORD_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_discord_application_id
DISCORD_GUILD_ID=your_test_server_id
WOLVESVILLE_API_KEY=your_wolvesville_api_key
lang=en

The optional variables already have defaults in .env.example:

lang=en
WOLVESVILLE_API_BASE_URL=https://api.wolvesville.com
WOLVESVILLE_API_TIMEOUT_MS=10000

lang=en is the default and makes command descriptions, choices, embeds, and error messages use English. Change it to lang=vi for Vietnamese. BOT_LANG=en|vi is also supported and takes precedence when both variables are present.

After changing the language, restart the bot and run npm run deploy again so Discord refreshes the slash-command descriptions.

.env is excluded by .gitignore. Before every commit, verify that no real token or API key has been added to the repository.

4. Register slash commands and run the bot

Register or update the commands:

npm run deploy

Start the bot:

npm start

During development, automatically restart when source files change:

npm run dev

Run npm run deploy again whenever you change a command name, description, or option.

5. Self-host continuously

The npm start process must remain running. You can host it on a VPS, a home server, or any platform that supports long-running Node.js services. On a hosting platform, configure the same environment variables through its secrets manager instead of uploading .env when possible.

For production, leave DISCORD_GUILD_ID empty and run npm run deploy once to register global commands. Then run npm start as a long-running service and configure your platform to restart it if the process stops.

Clan bot access

Public clan data works with a clan ID. Some private data is only returned after the clan leader adds the Wolvesville Bot ID to the clan and grants the appropriate permissions. The API key is not the Bot ID; never give the API key to a clan leader.

The /clan command group intentionally calls only GET endpoints. Endpoints that can post messages, kick or block members, edit flairs, or modify quests are not implemented.

Error handling and rate limits

• Network commands use deferReply() to prevent interactions from expiring.
• Requests time out after 10 seconds by default; configure this with WOLVESVILLE_API_TIMEOUT_MS.
• The client retries HTTP 429 and temporary server errors up to two times, honors Retry-After, and caps each retry delay.
• Authentication, not-found, and rate-limit errors become private Discord responses.
• Usernames, result limits, locales, game modes, and clan UUIDs are validated.

Verify the project

npm run check
npm test

Security

• Never commit .env or hard-code tokens and API keys.
• Never log DISCORD_TOKEN or WOLVESVILLE_API_KEY.
• Use the Wolvesville Public API only in accordance with its current documentation and terms.

Wolvesville requests include Accept: application/json, Content-Type: application/json, and Authorization: Bot <API key> as required by the official documentation.

License

This project is released under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software subject to the license terms.