Invite Tracker

Know exactly who brings members to your server. The bot remembers every invite link and, when someone joins, credits the member who invited them. It also spots fake invites (brand-new accounts), counts members who left, and can hand out roles automatically when someone reaches an invite goal. Perfect for invite contests and growth campaigns.

What it does

• Who invited whom: join and leave messages that name the inviter, including vanity URLs and single-use invites.
• Leaderboard: /leaderboard ranks your best inviters, /invites shows anyone's stats (regular, left, fake, bonus).
• Fake detection: accounts younger than a threshold you choose do not count.
• Reward roles: give a role automatically at 5, 10, 50 invites...
• Staff tools: add, remove or reset invites, and resync them.

1. Create the bot on Discord

1. Open the Discord Developer Portal and click New Application.
2. On General Information, copy the Application ID (CLIENT_ID).
3. Go to Bot, click Reset Token and copy it (DISCORD_TOKEN).
4. Still on Bot, turn on Server Members Intent.
5. Go to OAuth2 > URL Generator, tick bot and applications.commands, give it Manage Server (to read invites), Manage Roles (for rewards), Send Messages and Embed Links, then add it to your server. Put the bot's role above the reward roles.

2. Deploy

Fill the variables and click Deploy. Set GUILD_ID to your server ID to get the commands instantly (global commands can take a few minutes).

3. Configure

• /config channel: where join and leave messages go.
• /config message: customize the join and leave texts.
• /config fake-threshold: minimum account age (in days) for an invite to count.
• /reward add: give a role at a number of invites.
• /config view: check your settings. /help lists everything.

Good to know

• Invites created before the bot joined are picked up when it starts, so add the bot before your campaign.
• Data is saved in data/database.json with your files.

🎯 Discord Invite Tracker Bot

An advanced, production-ready Discord Invite Tracker Bot built with Discord.js v14. It delivers real-time invite tracking, Discord Vanity URL detection, anti-alt account filters, automated milestone role rewards, interactive paginated leaderboards, and fully customizable join/leave embed logs.

✨ Key Features

• ⚡ Real-Time Invite Caching Engine: Automatically captures and syncs invite uses across every guild without missing joins.
• 🌐 Vanity URL & OAuth Detection: Seamlessly distinguishes between regular invites, server vanity URLs (discord.gg/vanity), and bot integrations.
• 🛡️ Anti-Alt / Fake Account Detection: Automatically calculates account creation age on join. Accounts younger than a configurable threshold (e.g. 3 days) are flagged as Fake and excluded from valid invite totals.
• 🚪 Precise Member Departure Attribution: Tracks which user originally invited a departing member and automatically adjusts the inviter's stats (left + 1, regular - 1).
• 🎖️ Automated Milestone Role Rewards: Set up reward milestones (e.g., 5 invites ➔ Bronze, 10 invites ➔ Silver). The bot awards roles instantly when goals are met.
• 🏆 Interactive Paginated Leaderboard: Dynamic top 10 inviters display with gold, silver, and bronze badges (🥇 🥈 🥉) and interactive button navigation (◀️ Previous / Next ▶️).
• 📊 Detailed User Profile (/invites): View regular, left, fake, and bonus invites, win retention rate %, active invite codes, and a visual progress bar toward the next milestone.
• 📝 Rich Template Interpolation: Customize welcome and leave messages with dynamic variables ({user}, {inviter}, {invites}, {total}, {guild.name}, {code}, {memberCount}).
• 💾 Zero-Dependency Atomic Storage: Fast, persistent JSON database with in-memory caching and atomic temporary writes to eliminate race conditions and corrupted data.
• 🛡️ Slash Commands Only: Built exclusively with Discord Application (/) Slash Commands, compliant with modern Discord API standards.

📸 Preview & Showcase

+-----------------------------------------------------------+
| 📊 Invite Statistics — Hashir                             |
| Detailed invite breakdown and tracking record.             |
|                                                           |
| 🎯 Total Invites: 24 Invites                              |
| ✅ Regular: 26 members    | 🚪 Left: 3 departed           |
| 🤖 Fake/Alt: 1 flagged    | 🎁 Bonus: +2 awarded          |
| 📈 Retention Rate: 90% retained                           |
|                                                           |
| 🎖️ Milestone Progress                                     |
| Next Goal: @Gold Inviter (30 invites)                     |
| [▰▰▰▰▰▰▰▰▱▱] 80% (6 more needed)                        |
|                                                           |
| 🔗 Active Invite Links                                    |
| • discord.gg/abcXYZ — 14 uses                             |
| • discord.gg/def123 — 12 uses                             |
+-----------------------------------------------------------+

📋 Slash Commands Reference

📊 Member Commands

⚙️ Server Configuration (Manage Guild Required)

🎖️ Role Rewards (Manage Roles Required)

⚡ Administration (Administrator or Manage Guild Required)

🏷️ Message Template Variables

You can use the following placeholders inside /config message:

🚀 Quick Setup & Installation

1. Prerequisites

• Node.js: v18.0.0 or higher
• Discord Bot Token: From the Discord Developer Portal

2. Enable Privileged Gateway Intents

In the Discord Developer Portal:

1. Select your Application ➔ Bot tab.
2. Scroll down to Privileged Gateway Intents.
3. Enable Server Members Intent (GUILD_MEMBERS).
4. Ensure the bot has permissions to:
   • Manage Server (to fetch server invites)
   • Manage Roles (to grant milestone role rewards)
   • Send Messages & Embed Links

3. Clone Repository & Install Dependencies

# Clone the repository
git clone https://github.com/hashiryahya/discord-invite-tracker.git

# Navigate to project directory
cd discord-invite-tracker

# Install required dependencies
npm install

4. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Open .env and fill in your credentials:

DISCORD_TOKEN=your_bot_token_here
CLIENT_ID=your_application_client_id_here
GUILD_ID=your_test_guild_id_here   # Optional: For instant testing
DATABASE_PATH=./data/database.json

5. Register Slash Commands

npm run deploy-commands

6. Start the Bot

# Production mode
npm start

# Development mode (auto-reload on code change)
npm run dev

🐳 Docker Deployment

A Dockerfile is provided for containerized deployments:

# Build the Docker image
docker build -t discord-invite-tracker .

# Run the container
docker run -d --name invite-bot \
  -e DISCORD_TOKEN="your_token" \
  -e CLIENT_ID="your_client_id" \
  -v $(pwd)/data:/app/data \
  --restart unless-stopped \
  discord-invite-tracker

📁 Project Architecture

discord-invite-tracker/
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore patterns
├── Dockerfile                # Docker container configuration
├── LICENSE                   # MIT License
├── package.json              # NPM package manifest & scripts
├── README.md                 # Project documentation
├── data/
│   ├── .gitkeep              # Git tracking placeholder
│   └── database.json         # Persistent JSON database (auto-generated)
└── src/
    ├── config.js             # Configuration defaults loader
    ├── deploy-commands.js    # Slash command registration script
    ├── index.js              # Application entry point & client init
    ├── commands/             # Slash commands organized by category
    │   ├── admin/
    │   │   ├── addInvites.js
    │   │   ├── config.js
    │   │   ├── removeInvites.js
    │   │   ├── resetInvites.js
    │   │   ├── reward.js
    │   │   └── syncInvites.js
    │   ├── general/
    │   │   ├── help.js
    │   │   └── ping.js
    │   └── invites/
    │       ├── invites.js
    │       └── leaderboard.js
    ├── database/
    │   └── db.js             # Atomic, thread-safe JSON database service
    ├── events/               # Discord Gateway event handlers
    │   ├── guildCreate.js
    │   ├── guildDelete.js
    │   ├── guildMemberAdd.js
    │   ├── guildMemberRemove.js
    │   ├── interactionCreate.js
    │   ├── inviteCreate.js
    │   ├── inviteDelete.js
    │   └── ready.js
    ├── services/
    │   └── inviteTracker.js  # Real-time invite detection & caching engine
    └── utils/
        └── formatters.js     # Template parser, duration & embed helpers

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

1. Fork the Project (git checkout -b feature/AmazingFeature)
2. Commit your Changes (git commit -m 'Add some AmazingFeature')
3. Push to the Branch (git push origin feature/AmazingFeature)
4. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

👨‍💻 Author

Hashir Yahya

• Website: hashiryahya.online
• GitHub: @hashiryahya
• Portfolio: hashiryahya.github.io