/ fluxer / developers / bot-guide

Building a Bot on Fluxer

A complete guide - from enabling developer mode inside the Fluxer app, to writing and running your first bot with @fluxerjs/core. No prior Fluxer experience needed.

Node.js 18+ @fluxerjs/core ES Modules
Fluxer's API is intentionally similar to Discord's, so most patterns will feel familiar if you've written Discord bots before. The main differences are the package name, where your application lives, and how you get your token.
/ fluxer / beginners / bot-guide

Your First Fluxer Bot

In this guide, you'll create a bot from scratch - no prior experience needed! We'll go slow and explain everything in plain English. By the end, you'll have a working bot that responds to commands.

Totally Free Beginner Friendly Step by Step
What is a bot? A bot is like a virtual assistant that lives in your server. It can automatically respond to messages, welcome new members, moderate content, and much more!

Enable Developer Mode

The developer tools are built into the Fluxer app - there's no separate website portal.

Fluxer doesn't have a browser-based developer portal. Everything for creating and managing bot applications lives directly inside the client. You unlock it by toggling Developer Mode in the app settings.

1
Open Settings

Click the gear icon next to your username at the bottom-left of the Fluxer window. You can also use Ctrl+, on Windows/Linux or Cmd+, on macOS.

2
Go to the Advanced tab

Scroll down the settings sidebar until you see the Advanced tab and click it.

3
Turn on Developer Mode

Find the Developer Mode toggle and switch it on. The toggle turns blue when active.

4
Find the Developer section

A Developer entry will appear in the settings sidebar. This is where you create applications, manage bots, and copy tokens.

Settings - Advanced
Settings / Advanced
Developer Mode Unlocks the Developer section and adds Copy ID options to right-click menus.
Developer Mode also adds a Copy ID option to the right-click menu on users, messages, channels, and servers - useful when referencing specific resources in your bot code.

Step 1: Enable Developer Mode

Unlocking the bot-building features in Fluxer.

Think of Developer Mode as a secret switch that reveals all the advanced features in Fluxer - the ones you need to create bots!

1
Open Settings

Look for the gear icon at the bottom-left of Fluxer and click it. Or simply press Ctrl+, (Windows) or Cmd+, (Mac).

2
Find the Advanced tab

On the left side of Settings, scroll down until you see Advanced - click on it.

3
Turn on Developer Mode

Find the Developer Mode toggle and flip it ON. It turns blue when it's active.

4
Look for the Developer section

A new Developer option now appears in your Settings! This is where you'll create and manage your bots.

Pro tip: With Developer Mode on, you can right-click on almost anything (users, messages, channels) to Copy ID - this is super handy for telling your bot exactly what to look at!

Create an Application

Register your bot and grab its token from the Developer section.

With Developer Mode on, go to Settings > Developer. You'll see a list of your existing applications, or an empty state if this is your first one.

1
Create a new application

Click New Application, give it a name, and confirm. The name is what shows in server member lists when your bot is online.

2
Add a bot user

Inside the application settings, go to the Bot tab and click Add Bot. This turns the application into an actual bot account.

3
Copy your token

Click Reset Token to generate one and copy it right away. You won't see it again after leaving the screen.

4
Generate an invite URL

Go to the OAuth2 tab, pick the bot scope, choose the permissions your bot needs, then copy the generated invite URL.

Keep your token private. Anyone with it has full control over your bot account. Don't put it in source code, don't paste it in chat. If it leaks, reset it from the Developer section immediately.

Step 2: Create Your Bot Account

Setting up your bot so it can come online.

Now that Developer Mode is enabled, let's create your bot! Go to Settings - Developer on the left side of Fluxer.

1
Create a New Application

Click the + New Application button. Give your bot a cool name like "MyFirstBot" or "ServerHelper" - this is what people will see!

2
Add a Bot User

Inside your new application, go to the Bot tab and click Add Bot. This turns your application into an actual bot account.

3
Get Your Secret Token

Click Reset Token to generate a secret password for your bot. COPY IT NOW and save it somewhere safe - you won't see it again!

4
Create an Invite Link

Go to the OAuth2 tab, pick the bot option, choose what permissions your bot needs, then copy the invite URL.

IMPORTANT - Keep your token secret! Your token is like your bot's password. Never share it with anyone or post it anywhere. If someone gets it, they can control your bot! If you accidentally share it, go back to Developer settings and reset it immediately.

Invite the Bot to a Server

Authorize your bot to join a guild you own or manage.

Paste the OAuth2 invite URL into your browser. You'll be prompted to pick a server - choose one where you have the Manage Server permission, then click Authorize.

The bot will appear offline in the member list until you start your process. Set up a private test server so you can work without affecting anyone else.

The same invite URL works for adding the bot to multiple servers later, as long as the OAuth2 scope and permissions stay the same.

Project Setup

Initialize a Node.js project and install the Fluxer library.

You need Node.js 18 or newer. Create a directory for your bot and initialize it:

bash
mkdir my-fluxer-bot && cd my-fluxer-bot
npm init -y

Install @fluxerjs/core and dotenv:

bash
npm install @fluxerjs/core dotenv

The library uses ES module syntax. Open package.json and add "type": "module":

package.json
{
  "name":    "my-fluxer-bot",
  "version": "1.0.0",
  "type":    "module",
  "main":    "index.js"
}

Create a .env file at the project root for your token:

.env
FLUXER_BOT_TOKEN=your-bot-token-here
Add .env to .gitignore before your first commit. Running echo ".env" >> .gitignore takes care of it.

File structure

tree
my-fluxer-bot/
├── .env
├── .gitignore
├── index.js
├── package.json
└── node_modules/

Writing the Bot

The entry point and your first working command.

Create index.js. This logs in, ignores other bots, and responds to !ping with the measured round-trip latency:

index.js
import { Client, Events } from '@fluxerjs/core';
import 'dotenv/config';

const client = new Client({ intents: 0 });

client.on(Events.Ready, () => {
  console.log(`Logged in as ${client.user.tag}`);
});

client.on(Events.MessageCreate, async (message) => {
  if (message.author.bot) return;

  if (message.content === '!ping') {
    const t   = Date.now();
    const msg = await message.reply('Pong!');
    await msg.edit(`Pong! \`${Date.now() - t}ms\``);
  }
});

client.on(Events.Error, console.error);

await client.login(process.env.FLUXER_BOT_TOKEN);

What each part does

-
new Client({ intents: 0 })

Creates the bot client. intents: 0 requests no privileged gateway data. If you need to read message content from other users, enable the Message Content intent in the Developer section and set its bitmask value here.

-
Events.Ready

Fires once after login completes and the gateway is up. client.user is available at this point.

-
message.author.bot guard

Skips messages from any bot account. Without this, two bots in the same channel can trigger each other in a loop.

-
Events.Error handler

Prevents gateway errors from throwing unhandled exceptions and crashing the process. Passing console.error is a reasonable minimum.

-
client.login()

Authenticates and opens the WebSocket connection to the gateway. Always call this last.

Handling multiple commands

A prefix-based switch keeps things clean without pulling in extra libraries:

index.js
client.on(Events.MessageCreate, async (message) => {
  if (message.author.bot) return;

  const prefix = '!';
  if (!message.content.startsWith(prefix)) return;

  const [cmd, ...args] = message.content
    .slice(prefix.length).trim().split(/\s+/);

  try {
    switch (cmd.toLowerCase()) {
      case 'ping':
        await message.reply('Pong!');
        break;
      case 'hello':
        await message.reply(`Hey, ${message.author.username}.`);
        break;
      case 'echo':
        await message.reply(args.join(' ') || 'Nothing to echo.');
        break;
    }
  } catch (err) {
    console.error('Command failed:', err);
  }
});

Running the Bot

Start the process and test it.

bash
node index.js

If the token is valid and the gateway connects, you'll see:

output
Logged in as MyBot#1234

Go into a channel the bot can read and write in, type !ping, and it should reply with Pong! and the latency.

Install nodemon as a dev dependency and use npx nodemon index.js - it restarts the bot automatically on every file save.
Don't rely on node index.js in a terminal for production - it stops when the session closes. Use PM2 or a Docker container instead.

Step 3: Start Your Bot!

Making your bot come alive.

This is the fun part - getting your bot online! Open your terminal (Command Prompt on Windows, Terminal on Mac) and navigate to your bot's folder.

terminal
node index.js

If everything worked, you should see this message:

Success!
Logged in as MyBot#1234

Now go to your server, find a text channel, and type !ping. Your bot should reply with Pong! - congratulations, you made a working bot!

Pro tip: Want your bot to restart automatically when you save changes? Run npm install nodemon, then use npx nodemon index.js instead!
Remember: if you close the terminal window, your bot goes offline! For a bot that runs 24/7, you'll need to host it on a server or use a service like PM2.

Classes

Main exports from @fluxerjs/core.

Client
Root bot class. Manages login, the gateway connection, event dispatching, and caches for guilds, channels, and users.
Gateway
Manages the WebSocket connection - connecting, heartbeating, reconnecting, and resuming sessions after disconnects.
REST
HTTP client for direct API calls. Attaches auth headers and handles rate limits automatically.
Events
Constants for event names. Prefer these over raw strings for autocomplete support and to avoid typos.

Client constructor options

OptionTypeDescription
intents number Bitmask of gateway intents. Controls which events the gateway forwards. Use 0 for basic use with no privileged data.
presence object Initial presence set on login - status, activity, etc. Optional.
rest object Forwarded to the REST client. Set baseUrl here when targeting a self-hosted Fluxer instance.

Using REST directly

You can instantiate the REST class on its own for cases where a higher-level method doesn't exist yet:

rest-example.js
import { REST, Routes } from '@fluxerjs/core';
import 'dotenv/config';

const rest   = new REST().setToken(process.env.FLUXER_BOT_TOKEN);
const guilds = await rest.get(Routes.userGuilds());

console.log(`Bot is in ${guilds.length} guild(s).`);

Events

What you can listen to via client.on().

Events.Ready
Fires once after login and the gateway connection is up. client.user is set at this point.
Events.MessageCreate
Fires when a message is posted in any channel the bot can see. Payload is a Message object.
Events.MessageUpdate
Fires when a message is edited. Receives the old and new message - old may be partial if it wasn't cached.
Events.MessageDelete
Fires when a message is deleted. The message object may be partial if it wasn't in cache.
Events.GuildCreate
Fires when the bot joins a guild, or when guild data becomes available on startup.
Events.GuildDelete
Fires when the bot is removed from a guild or the guild goes unavailable.
Events.GuildMemberAdd
Fires when someone joins a guild the bot is in. Requires the Guild Members intent.
Events.GuildMemberRemove
Fires when a member leaves, is kicked, or is banned.
Events.Error
Fires on internal gateway errors. Handle this to stop the process crashing on unhandled rejections.

Permissions

Commonly used permission bits for bot invite URLs.

When generating the invite URL in the Developer section, the interface handles the bitwise combination for you - just check what your bot needs.

PermissionBitWhen you need it
Send Messages2048Required to post any message in a text channel.
Read Message History65536Access to past messages. Needed for context-aware features.
Embed Links16384Sending rich embeds with fields, images, and colors.
Attach Files32768Uploading files and images as message attachments.
Add Reactions64Adding emoji reactions to messages.
Manage Messages8192Deleting or pinning messages. Treat as a privileged permission.
Connect1048576Joining voice channels. Only needed for audio bots.

Advanced Patterns

Techniques for bots that grow beyond a single file.

Sending embeds

index.js
if (cmd === 'info') {
  await message.channel.send({
    embeds: [{
      title:       'Bot Info',
      description: 'Running on Fluxer.',
      color:       0x4f80f5,
      fields: [
        { name: 'Guilds', value: `${client.guilds.cache.size}`, inline: true },
        { name: 'Uptime',  value: `${Math.floor(process.uptime())}s`, inline: true }
      ],
      timestamp: new Date().toISOString()
    }]
  });
}

Splitting commands into separate files

Once you have more than a few commands, a commands/ folder with one file per command keeps things manageable:

tree
my-fluxer-bot/
├── index.js
└── commands/
    ├── ping.js
    ├── info.js
    └── echo.js
commands/ping.js
export const name = 'ping';

export async function execute(message) {
  await message.reply('Pong!');
}
index.js - with loader
import { Client, Events } from '@fluxerjs/core';
import { readdir } from 'node:fs/promises';
import 'dotenv/config';

const client   = new Client({ intents: 0 });
const commands = new Map();

for (const file of await readdir('./commands')) {
  const mod = await import(`./commands/${file}`);
  commands.set(mod.name, mod);
}

client.on(Events.MessageCreate, async (message) => {
  if (message.author.bot || !message.content.startsWith('!')) return;
  const [name] = message.content.slice(1).split(' ');
  const cmd  = commands.get(name);
  if (cmd) await cmd.execute(message);
});

client.on(Events.Error, console.error);

await client.login(process.env.FLUXER_BOT_TOKEN);

Self-hosted instances

Point your bot at a self-hosted Fluxer server by setting rest.baseUrl:

index.js
const client = new Client({
  intents: 0,
  rest: {
    baseUrl: 'https://your-instance.example.com/api'
  }
});

See the self-hosting docs for running your own Fluxer backend.

Advanced Topics

For when you're ready to learn more!

The sections below (Classes, Events, Permissions, Advanced Patterns) are reference material for when you want to learn more about coding bots. For now, you have everything you need to make a working bot!

Come back to these sections later once you're comfortable with the basics. You can:

1
Learn about different events

Events tell your bot when something happens - like when someone joins the server, sends a message, or reacts to something.

2
Understand permissions

Permissions control what your bot can do - like sending messages, deleting messages, or joining voice channels.

3
Explore advanced patterns

Once your bot grows, you'll want to organize code into multiple files and use more complex features.

You've already made a bot! That's the hardest part. The rest is just learning new tricks as you go.