A lightweight, fully-featured Discord AFK bot built with discord.js v14. When a user sets themselves as AFK, the bot automatically notifies others who mention them, tracks how long they've been away, and welcomes them back when they return.
- Set AFK status with a custom reason using
!afk - Mention detection — instantly notifies the sender if they ping an AFK user
- Auto-return — AFK status is automatically cleared when the user sends any message
- Manual return — use
!backto explicitly remove your AFK status - Duration tracking — shows exactly how long you were away
- Nickname tagging — automatically prepends
[AFK]to the user's server nickname (requires Manage Nicknames permission) - Auto-delete — bot replies auto-delete after a few seconds to keep channels clean
- Embed-based UI — clean, color-coded Discord embeds for all responses
| Action | Description |
|---|---|
!afk studying |
Sets your status to AFK with reason "studying" |
@mention an AFK user |
Bot warns the sender that the user is AFK |
| Send any message | Bot auto-removes your AFK status and shows duration |
!back |
Manually removes your AFK status |
- Node.js v16.11.0 or higher
- A Discord bot token from the Discord Developer Portal
git clone https://github.com/YOUR_USERNAME/afk-bot.git
cd afk-botnpm installCopy the example environment file and fill in your credentials:
cp .env.example .envOpen .env and add your bot token:
DISCORD_TOKEN=your_bot_token_here
CLIENT_ID=your_client_id_here- Go to the Discord Developer Portal
- Click New Application → give it a name
- Navigate to Bot → click Reset Token and copy the token
- Under Privileged Gateway Intents, enable:
- ✅ Server Members Intent
- ✅ Message Content Intent
- Navigate to OAuth2 → URL Generator
- Select scopes:
bot - Select permissions:
Send Messages,Read Messages/View Channels,Manage Nicknames,Embed Links - Copy the generated URL, paste it in your browser, and invite the bot to your server
# Production
npm start
# Development (auto-restarts on file changes)
npm run devYou should see:
✅ Logged in as YourBot#1234
📡 Serving 1 server(s)
| Command | Description | Example |
|---|---|---|
!afk [reason] |
Set yourself as AFK with an optional reason | !afk in a meeting |
!back |
Manually remove your AFK status | !back |
Note: AFK status is also automatically removed when you send any message in the server.
afk-bot/
├── src/
│ ├── index.js # Bot entry point — client setup & event listeners
│ └── afkManager.js # Core AFK logic — set, check, clear, format
├── .env.example # Environment variable template
├── .gitignore # Files excluded from version control
├── package.json # Project metadata & dependencies
└── README.md # You are here
- User runs
!afk→ their user ID is stored in aMapwith the reason and timestamp. - Someone sends a message with mentions → the bot checks each mentioned user against the AFK map.
- AFK user sends any message → the bot automatically clears their entry from the map and shows how long they were away.
- Nickname tagging → if the bot has
Manage Nicknamespermission and the member is below the bot in the role hierarchy,[AFK]is prepended to their nickname and removed on return.
| Permission | Purpose |
|---|---|
Send Messages |
Required to send AFK notifications |
Embed Links |
Required to send embed messages |
Read Message History |
Required to read messages for mention detection |
Manage Nicknames |
(Optional) Adds [AFK] prefix to the user's nickname |
- discord.js v14 — Discord API library
- dotenv — Environment variable management
- Node.js — JavaScript runtime
Contributions, issues, and feature requests are welcome!
- Fork the repository
- Create a new branch:
git checkout -b feature/your-feature-name - Commit your changes:
git commit -m "Add: your feature description" - Push to the branch:
git push origin feature/your-feature-name - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
- Slash command (
/afk) support - Per-server AFK prefix customization
- Persistent AFK storage using a database (SQLite / MongoDB)
- Auto-clear AFK after a configurable timeout
- DM the AFK user a summary of who mentioned them while they were away
Made with ❤️ as a daily GitHub project.