Welcome to Firefly
Firefly is a feature-rich Discord bot designed to enhance your server with leveling, music, moderation, economy, and AI capabilities. This documentation will help you get the most out of Firefly.
What Can Firefly Do?
- Leveling & XP System - Reward active members with XP, levels, and custom role rewards
- Music Player - High-quality music playback with queue management, filters, and 24/7 mode
- Moderation Tools - Keep your server safe with kick, ban, mute, warn, and more
- Economy System - Virtual currency with daily rewards, work, shop, and gambling
- AI Chat - Powered by Google Gemini with bring-your-own-key support
- Reaction Roles - Let members self-assign roles by clicking emoji reactions
- Ticket System - Private support channels for members to get help from staff
- Utility Commands - Server info, user info, avatars, and more
Premium Tiers
Firefly offers four tiers to match your server's needs:
- Free - Core features including leveling, economy, moderation, and utility commands
- Plus ($5/mo) - Adds music playback, autoplay, and AI chat (BYOK)
- Pro ($12/mo) - Adds 24/7 mode, advanced filters, AI image generation, and lockdown
- Ultra ($25/mo) - Everything included plus AI without key setup and priority support
Ready to get started? Check out the Quick Start Guide to add Firefly to your server in minutes.
Quick Start Guide
Get Firefly up and running on your server in just a few steps.
Step 1: Invite Firefly
Click the button below to add Firefly to your Discord server. You'll need the Manage Server permission.
Step 2: Configure Settings
Once Firefly is in your server, use the /settings command to open the configuration panel. From here you can:
- Enable or disable features (leveling, economy, music, etc.)
- Set up level-up notifications and reward roles
- Configure moderation logging
- Set your AI API key (for Plus/Pro tiers)
/settings
Step 3: Set Up Permissions
Firefly needs certain permissions to function properly. Make sure the bot role has:
- Send Messages - Required for all responses
- Embed Links - For rich command responses
- Manage Roles - For level reward roles
- Connect & Speak - For music playback
- Moderate Members - For timeout/mute commands
- Ban Members - For ban commands
The Firefly role must be positioned above any roles you want it to manage (for level rewards) or moderate (for kicks/bans).
Step 4: Start Using Commands
Firefly uses Discord's slash commands. Type / in any channel to see available commands. Try these to get started:
/help- View all available commands/rank- Check your current level and XP/leaderboard- See top members by XP/daily- Claim your daily coins
Permissions Guide
Understanding permission requirements and command access levels.
Bot Permissions
Firefly requires these permissions to function properly:
| Permission | Required For |
|---|---|
Send Messages |
All command responses |
Embed Links |
Rich embeds (rank cards, leaderboards, etc.) |
Attach Files |
Rank card images, AI-generated images |
Manage Roles |
Assigning level reward roles |
Manage Messages |
Purge command |
Moderate Members |
Mute/timeout command |
Kick Members |
Kick command |
Ban Members |
Ban command |
Connect |
Joining voice channels for music |
Speak |
Playing audio in voice channels |
User Permission Levels
Commands require different permission levels to use:
| Level | Who Can Use | Example Commands |
|---|---|---|
| Everyone | Any server member | /rank, /daily, /balance |
| Moderator | Users with Moderate Members permission | /mute, /warn, /purge |
| Admin | Users with Administrator permission | /ban, /xp give, /settings |
| Server Owner | Only the server owner | /settings (premium features) |
Server administrators can customize which roles have access to moderation commands using /settings.
Moderation Commands
Keep your server safe and well-managed with these moderation tools.
Remove a user from your server. They can rejoin with a new invite.
- user
- The member to kick (required)
- reason
- Optional reason shown in audit log
Permanently ban a user from your server.
- user
- The member to ban (required)
- reason
- Optional reason for the ban
- delete_messages
- Delete messages from past 1-7 days
Timeout a user for a specified duration. Uses Discord's native timeout feature.
- user
- The member to mute (required)
- duration
- How long to mute (e.g., 10m, 1h, 1d)
- reason
- Optional reason for the timeout
Issue an official warning to a user. Warnings are logged and can be reviewed later.
Bulk delete messages in a channel. Cannot delete messages older than 14 days (Discord limitation).
- amount
- Number of messages to delete (1-100)
- user
- Only delete messages from this user
Set a slowmode delay on the current channel.
- duration
- Delay between messages (0 to disable, max 6h)
Lock a channel to prevent all messages. Useful during raids or emergencies.
Leveling Commands
Engage your community with XP, levels, and role rewards.
How Leveling Works
Members earn XP by chatting in your server. The amount of XP depends on message length and includes a cooldown to prevent spam. When members level up, they can receive announcements and role rewards.
XP is earned every 60 seconds per user to prevent spam farming. Longer messages earn slightly more XP.
View your current level, XP, and progress to the next level. Displays a visual rank card.
- user
- View another member's rank (optional)
Display the top members by XP in your server.
Award XP to a member. Requires administrator permission.
Remove XP from a member. Requires administrator permission.
Reset a member's XP to zero. Requires administrator permission.
XP Formula
The XP required for each level follows this progression:
XP Required = 100 * level^1.5
For example:
- Level 1: 100 XP
- Level 5: 1,118 XP
- Level 10: 3,162 XP
- Level 25: 12,500 XP
- Level 50: 35,355 XP
Music Commands
High-quality music playback with queue management and audio filters.
Music features require Plus tier or higher. Upgrade to Premium
Play a song or add it to the queue. Supports Spotify, Apple Music, SoundCloud, and Deezer links, or search by name.
- query
- Song name, URL, or playlist link
Pause the currently playing track. Use /resume to continue.
Skip to the next song in the queue.
View the current music queue with track durations.
Display detailed info about the currently playing track including progress bar.
Adjust the playback volume (0-150%).
Apply audio filters to playback. Available filters: bassboost, nightcore, vaporwave, 8D, karaoke.
Automatically queue similar songs when the queue is empty.
Keep Firefly connected to the voice channel 24/7, even when no one is listening.
Supported Sources
- Spotify - Tracks, albums, and playlists
- Apple Music - Songs, albums, and playlists
- SoundCloud - Tracks and playlists
- Deezer - Tracks, albums, and playlists
- Direct URLs - MP3, OGG, WAV files
Economy Commands
Virtual currency system with daily rewards, work, shops, and more.
Check your wallet and bank balance.
Claim your daily coin reward. Resets at midnight UTC.
Work a random job to earn coins. Has a cooldown between uses.
Browse items available in the server shop. Server admins can add custom items.
Purchase an item from the shop using your coins.
Send coins to another member.
Move coins from your wallet to your bank for safekeeping.
Move coins from your bank to your wallet.
Risk your coins for a chance to double them. Games include coinflip, slots, and dice.
AI Assistant
Chat naturally with Firefly by mentioning it. The AI can answer questions and execute commands for you.
BYOK (Bring Your Own Key): Plus and Pro tiers require you to set your own Gemini API key in /settings. Ultra tier includes AI without any setup required.
How to Talk to Firefly
Simply mention Firefly in any message to start a conversation:
@Firefly hey, how are you?
@Firefly what's the capital of France?
@Firefly tell me a joke
Firefly responds naturally and maintains conversation context, so you can have flowing discussions without repeating yourself.
AI Command Execution
The AI isn't just for chatting - it can execute bot commands on your behalf. Just ask naturally:
@Firefly play some lo-fi music
// Firefly plays lo-fi hip hop in your voice channel
@Firefly how much money do I have?
// Firefly shows your balance
@Firefly who has the most XP?
// Firefly shows the leaderboard
@Firefly skip this song
// Firefly skips to the next track
The AI understands natural language and figures out what you want. It respects permission levels - it won't run moderation actions unless you have the required permissions.
AI Settings
Server admins can configure AI behavior in /settings > AI Settings:
- Mention Replies - Enable or disable AI responses when Firefly is mentioned
- AI Commands - Allow or prevent the AI from executing bot commands
- AI Channel - Restrict AI interactions to specific channels only
- Gemini API Key - Your personal API key (Plus/Pro tiers)
If your server prefers members use slash commands directly, you can disable mention replies and AI command execution while keeping slash commands available.
Getting a Gemini API Key
For Plus and Pro tiers, you'll need a free Gemini API key:
- Go to Google AI Studio
- Sign in with your Google account
- Click "Create API Key"
- Copy the key and add it in
/settings> AI Settings
Gemini API keys are free and include generous limits (60 requests/minute, 1,500/day). Your key is stored securely and only used for your server.
Utility Commands
Helpful tools for server information and user management.
View all available commands organized by category.
Open the server settings panel. Requires administrator permission.
Check the bot's response time and API latency.
Display detailed information about your server including member counts, boost level, and creation date.
View information about a user including their roles, join date, and account creation date.
Get a high-resolution version of a user's avatar.
Check your server's premium status and manage subscriptions.
Redeem an activation key for premium, tokens, or boosts.
Server Settings
Configure Firefly to match your server's needs using the settings menu.
Accessing Settings
Use /settings to open the interactive settings menu. You need administrator permission to access this.
Available Settings
General
- Prefix - Legacy text command prefix (slash commands are always available)
- Language - Bot response language
- Premium Tier - View or manage your subscription
Leveling
- Enable/Disable - Toggle the leveling system
- Level-up Channel - Where to send level-up announcements
- Level-up Message - Customize the announcement message
- XP Multiplier - Boost XP gain (Premium feature)
- Ignored Channels - Channels where XP is not earned
- Ignored Roles - Roles that don't earn XP
Economy
- Enable/Disable - Toggle the economy system
- Currency Name - Customize your server's currency name
- Starting Balance - Coins new members receive
- Daily Amount - Coins from /daily command
Moderation
- Mod Log Channel - Log all mod actions to a channel
- Auto-Mod Rules - Configure automatic moderation
AI (Plus+ Only)
- Gemini API Key - Your personal API key for AI features
- AI Channel - Restrict AI to specific channels
Level Rewards
Automatically assign roles when members reach certain levels.
Setting Up Level Roles
- Open
/settings - Navigate to "Leveling" section
- Select "Level Rewards"
- Add roles with their required levels
Role Stacking
By default, members keep all earned level roles. You can configure this behavior:
- Stack - Keep all earned roles (default)
- Replace - Only keep the highest earned role
Make sure Firefly's role is above any roles you want it to assign. Discord prevents bots from managing roles above their own.
Example Setup
| Level | Role |
|---|---|
| 5 | @Newcomer |
| 10 | @Regular |
| 25 | @Active Member |
| 50 | @Veteran |
| 100 | @Legend |
Reaction Roles
Let members self-assign roles by reacting to a message with an emoji.
How It Works
Reaction roles allow you to create self-service role menus. Post a message listing your roles, add emoji reactions, and members can click to get the role they want. No more asking admins for roles.
Reaction roles support three modes: Toggle (add/remove on react), Add only (react to get role), and Remove only (react to remove role).
Setting Up Reaction Roles
- Create a message in a channel (e.g., "React to get your roles!")
- Copy the message ID (right-click the message → Copy ID)
- Use
/reactionrole addto link an emoji to a role - Firefly automatically adds the emoji reaction to the message
- Members can now react to get the role
To copy a message ID, enable Developer Mode in Discord settings (App Settings → Advanced → Developer Mode).
Add a reaction role to a message. The emoji becomes clickable to get the role.
- message_id
- The ID of the message to add the reaction to
- emoji
- The emoji to react with (standard or custom server emoji)
- role
- The role to give when members react
- mode
- Optional: toggle (default), add, or remove
Remove a reaction role from a message.
- message_id
- The ID of the message
- emoji
- The emoji to remove
View all reaction roles configured in your server.
Reaction Role Modes
| Mode | Behavior |
|---|---|
toggle |
React to add role, remove reaction to remove role (default) |
add |
React to add role, removing reaction does nothing |
remove |
React to remove role (useful for opt-out systems) |
Example Setup
Here's how to create a color role picker:
1. Post your role menu message:
"Pick your favorite color!"
2. Add each reaction role:
/reactionrole add message_id:123456789 emoji:🔴 role:@Red
/reactionrole add message_id:123456789 emoji:🔵 role:@Blue
/reactionrole add message_id:123456789 emoji:🟢 role:@Green
Firefly's role must be above the roles you want it to assign. Move the Firefly role higher in Server Settings → Roles.
Ticket System
Create a support ticket system for your server. Members can open private channels to get help from your staff.
How Tickets Work
When a member creates a ticket, Firefly creates a private channel only visible to them and your support team. Staff can help the member, add others to the conversation, and close the ticket when resolved.
Quick Setup
- Use
/ticket setupto configure your ticket system - Use
/ticket panelto send a ticket creation button - Members click the button to open a ticket
Configure the ticket system for your server. Requires Manage Server permission.
- category
- Category where ticket channels are created
- support_role
- Role that can see and manage all tickets
- log_channel
- Channel where ticket logs are sent when closed
Send an embed with a button members can click to create tickets.
- title
- Custom title for the panel (default: "Support Tickets")
- description
- Custom description text
Create a new support ticket. Alternative to clicking the panel button.
- reason
- Optional reason for opening the ticket
Close the current ticket. Only usable inside a ticket channel.
Add a user to the current ticket so they can see and participate.
Remove a user from the current ticket.
Ticket Permissions
| Action | Who Can Do It |
|---|---|
| Create ticket | Any member |
| Close ticket | Ticket creator, Support role, Manage Channels permission |
| Reopen ticket | Manage Channels permission |
| Delete ticket | Manage Channels permission |
| Add/remove users | Ticket creator, Support role, Manage Channels permission |
Ticket Lifecycle
- Created - Member opens ticket, private channel is created
- Open - Support team and member discuss the issue
- Closed - Issue resolved, channel locked but not deleted
- Deleted - Channel is permanently removed
After closing a ticket, staff can choose to reopen it if needed, or delete it permanently. Closed tickets remain visible for reference.
Best Practices
- Create a dedicated category for tickets to keep them organized
- Set up a support role so your team can access all tickets
- Use the log channel to keep records of closed tickets
- Place the ticket panel in a visible channel like #support or #help
There's a 5-minute cooldown between creating tickets to prevent spam.
AI Setup (BYOK)
Configure AI features with your own Gemini API key.
Why BYOK?
Plus and Pro tiers use a "Bring Your Own Key" system for AI. This gives you:
- Lower costs - Gemini API is free with generous limits
- Privacy - Your conversations stay with your key
- Control - You manage your own usage and limits
Step-by-Step Setup
- Visit Google AI Studio
- Sign in with a Google account
- Click "Create API Key in new project"
- Copy the generated key
- In Discord, use
/settings - Go to "AI Settings"
- Paste your API key and save
Your API key is encrypted and stored securely. Only Firefly can access it to process AI requests.
Usage Limits
The free Gemini API tier includes:
- 60 requests per minute
- 1,500 requests per day
- 1 million tokens per minute
This is more than enough for most servers. Ultra tier users don't need to worry about limits as AI is included.
Frequently Asked Questions
Quick answers to common questions.
How do I add Firefly to my server?
Click the "Add to Discord" button on our website or use this invite link. You'll need the "Manage Server" permission in the server you want to add Firefly to.
Is Firefly free to use?
Yes! Firefly's core features (leveling, economy, moderation, utility) are completely free. Premium tiers add music, AI, and advanced features for a monthly subscription.
Why isn't Firefly responding to commands?
Check these common issues:
- Firefly needs "View Channel" and "Send Messages" permissions
- Slash commands may take up to an hour to appear after adding the bot
- Try using
/pingto test if the bot is online - Check the status page for any outages
How do I cancel my premium subscription?
Use /premium in Discord and click "Manage Subscription" to access the billing portal. From there you can cancel, update payment, or change your plan. Your premium benefits continue until the end of your billing period.
Can I transfer my XP to another server?
No, XP and levels are server-specific. Each server has its own leaderboard and progress.
What music sources does Firefly support?
Firefly supports Spotify, Apple Music, SoundCloud, Deezer, and direct audio URLs. We use ISRC (International Standard Recording Code) to find and play tracks across different platforms.
How do I report a bug or request a feature?
Visit our Community page to submit bug reports and feature requests. You can also join our Discord server for direct support.
Troubleshooting
Solutions for common issues.
Slash Commands Not Showing
Problem: After adding Firefly, slash commands don't appear when typing /.
Solutions:
- Wait up to 1 hour - Discord caches commands and may take time to sync
- Refresh Discord (Ctrl+R on desktop, or force close on mobile)
- Check if the bot has "Use Application Commands" permission
- Remove and re-add the bot with the correct permissions
Bot Not Responding
Problem: Commands work for others but not for you.
Solutions:
- Check if you're blacklisted (contact support)
- Verify the bot can see the channel you're using
- Try in a different channel
Music Not Playing
Problem: The bot joins voice but no audio plays.
Solutions:
- Check your server's premium status with
/premium - Make sure the bot isn't muted in the voice channel
- Try a different song or source
- Verify the bot has "Connect" and "Speak" permissions
Level Roles Not Assigning
Problem: Members level up but don't receive their role.
Solutions:
- Firefly's role must be higher than the roles it needs to assign
- Firefly needs the "Manage Roles" permission
- Check that the role isn't a managed role (bot roles, integration roles)
AI Not Working
Problem: /ai command returns an error.
Solutions:
- Verify your Gemini API key is correct in
/settings - Check if your key has exceeded its rate limit
- Try generating a new API key
- Ultra tier users: contact support if issues persist
Still having issues? Join our Discord support server for help from our team.