Creating a Bot

Overview

Creating a bot on Fluxer involves registering an application, which automatically generates a bot user and authentication credentials. This guide walks you through the process.

Prerequisites

A Fluxer account (cannot be an unclaimed account)
Basic understanding of HTTP APIs
Secure storage for your bot token

Creating an Application

Using the API

Create a new application with a bot user:

POST /api/v1/oauth2/applications
Content-Type: application/json
Authorization: Bearer {your_user_token}

{
  "name": "My Awesome Bot",
  "bot_public": true,
  "bot_require_code_grant": false,
  "redirect_uris": []
}

name

string

required

The name of your bot (used to generate the bot username)

bot_public

boolean

default:"true"

Whether anyone can invite the bot to their guild

bot_require_code_grant

boolean

default:"false"

Whether the bot requires a full OAuth2 code grant flow

redirect_uris

string[]

OAuth2 redirect URIs (optional for bot-only applications)

Response

The API returns your application details including the bot token:

{
  "id": "123456789012345678",
  "name": "My Awesome Bot",
  "redirect_uris": [],
  "bot_public": true,
  "bot_require_code_grant": false,
  "bot": {
    "id": "123456789012345678",
    "username": "my_awesome_bot",
    "discriminator": "0001",
    "avatar": null,
    "banner": null,
    "bio": null,
    "token": "123456789012345678.dGhpcyBpcyBhIHNlY3JldCB0b2tlbiBleGFtcGxl",
    "mfa_enabled": false,
    "authenticator_types": [],
    "flags": 0
  },
  "client_secret": "Y2xpZW50X3NlY3JldF9leGFtcGxl"
}

The bot token is only shown once during creation. Store it securely immediately.

Understanding Bot Tokens

Token Format

Bot tokens follow this structure:

{application_id}.{base64url_encoded_secret}

Example breakdown:

123456789012345678 - Your application ID
. - Separator
dGhpcyBpcyBhIHNlY3JldCB0b2tlbiBleGFtcGxl - Base64URL-encoded random secret

Token Storage

BOT_TOKEN=123456789012345678.dGhpcyBpcyBhIHNlY3JldCB0b2tlbiBleGFtcGxl

Never commit tokens to version control. Use .env files and add them to .gitignore.

Bot User Generation

When you create an application, Fluxer automatically:

Generates Bot User ID: Derived from the application ID using applicationIdToUserId()
Creates Username: Sanitizes your application name:
- Replaces spaces, hyphens, dots with underscores
- Removes non-alphanumeric characters (except underscores)
- Truncates to 32 characters maximum
- Ensures minimum 2 characters (prefixes with “bot” if needed)
Assigns Discriminator: Finds an available 4-digit discriminator for the username

Username Examples

Application Name	Generated Username
My Awesome Bot	`my_awesome_bot`
Cool-Bot 2000	`cool_bot_2000`
@#$%	`bot`
Music🎵Player	`musicplayer`

If the sanitized username has no available discriminators, Fluxer generates a random username instead.

Bot User Properties

Bot users have the following characteristics:

{
  user_id: "123456789012345678",  // Derived from application ID
  username: "my_awesome_bot",
  discriminator: 1,
  global_name: null,              // Bots don't have display names
  bot: true,                       // Flagged as bot account
  system: false,
  email: null,                     // Bots have no email
  phone: null,                     // Bots have no phone
  password_hash: null,             // Bots can't log in
  avatar_hash: null,               // Set via profile update
  banner_hash: null,
  bio: null,
  flags: 0n,
  // MFA mirrors the owner's settings
  authenticator_types: ownerUser.authenticatorTypes
}

Customizing Your Bot

Update Bot Profile

Change your bot’s appearance and metadata:

PATCH /api/v1/oauth2/applications/{application_id}/bot
Content-Type: application/json
Authorization: Bearer {your_user_token}

{
  "username": "coolbot",
  "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
  "banner": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
  "bio": "A helpful bot for your server!",
  "bot_flags": 1048576  // FRIENDLY_BOT flag
}

username

string

New username (2-32 characters, alphanumeric + underscores)

avatar

string | null

Base64-encoded image data or null to remove

banner

string | null

Base64-encoded image data or null to remove

bio

string | null

Bot description (up to 190 characters)

bot_flags

number

Bot behavior flags (see Bot Flags section below)

Changing the username triggers discriminator reassignment. You cannot change the discriminator directly.

Bot Flags

Control bot behavior with these flags:

// UserFlags from @fluxer/constants/src/UserConstants
const FRIENDLY_BOT = 1n << 20n;                    // 1048576
const FRIENDLY_BOT_MANUAL_APPROVAL = 1n << 21n;    // 2097152

FRIENDLY_BOT (1048576):

Automatically accepts friend requests
Users can DM the bot without being friends
Ideal for support and utility bots

FRIENDLY_BOT_MANUAL_APPROVAL (2097152):

Requires manual approval for friend requests
Prevents auto-acceptance even with FRIENDLY_BOT flag
Use with FRIENDLY_BOT for controlled relationships

const FRIENDLY_BOT = 1 << 20;

await fetch(`https://api.fluxer.app/v1/oauth2/applications/${appId}/bot`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${userToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bot_flags: FRIENDLY_BOT
  })
});

Managing Your Bot

Rotating Bot Token

If your token is compromised, generate a new one:

POST /api/v1/oauth2/applications/{application_id}/bot/reset
Content-Type: application/json
Authorization: Bearer {your_user_token}

{
  "password": "your_account_password",  // Required for security
  "totp_code": "123456"                 // If you have 2FA enabled
}

Response:

{
  "token": "123456789012345678.bmV3X3NlY3JldF90b2tlbl9leGFtcGxl",
  "bot": {
    "id": "123456789012345678",
    "username": "my_awesome_bot",
    // ... other bot details
  }
}

Rotating the token immediately invalidates the old token and terminates all active Gateway connections.

Listing Your Applications

Retrieve all applications you own:

GET /api/v1/oauth2/applications/@me
Authorization: Bearer {your_user_token}

Deleting Your Bot

Permanently delete a bot application:

DELETE /api/v1/oauth2/applications/{application_id}
Authorization: Bearer {your_user_token}

Deleting a bot:

Removes it from all guilds
Anonymizes all messages sent by the bot
Marks the bot user as deleted
Cannot be undone

Inviting Your Bot

OAuth2 Authorization URL

Generate an invite link for your bot:

https://fluxer.app/oauth2/authorize?client_id={application_id}&scope=bot&permissions={permissions}

client_id

string

required

Your application ID

scope

string

required

Always bot for bot invitations

permissions

string

Bitfield of requested permissions (see Permissions section)

guild_id

string

Pre-select a specific guild (user must have MANAGE_GUILD permission)

Permission Calculation

Calculate the permissions bitfield:

import { Permissions } from '@fluxer/constants/src/ChannelConstants';

// Request multiple permissions
const permissions = 
  Permissions.SEND_MESSAGES |
  Permissions.READ_MESSAGE_HISTORY |
  Permissions.ADD_REACTIONS;

const inviteUrl = `https://fluxer.app/oauth2/authorize?` +
  `client_id=${applicationId}&` +
  `scope=bot&` +
  `permissions=${permissions}`;

Common Permission Sets

Basic Bot
Moderation Bot
Admin Bot

const permissions = 
  Permissions.VIEW_CHANNEL |
  Permissions.SEND_MESSAGES |
  Permissions.READ_MESSAGE_HISTORY;
// Bitfield: 68608

const permissions = 
  Permissions.VIEW_CHANNEL |
  Permissions.SEND_MESSAGES |
  Permissions.MANAGE_MESSAGES |
  Permissions.KICK_MEMBERS |
  Permissions.BAN_MEMBERS;
// Bitfield: 70662

const permissions = Permissions.ADMINISTRATOR;
// Bitfield: 8

Request only the permissions your bot actually needs. Users are more likely to authorize minimal permission requests.

Testing Your Bot

Verify Token

Test your bot token works:

curl -H "Authorization: Bot {bot_token}" \
  https://api.fluxer.app/v1/oauth2/applications/@me

Successful response:

{
  "id": "123456789012345678",
  "name": "My Awesome Bot",
  "bot_public": true,
  "bot_require_code_grant": false,
  "flags": 0,
  "bot": {
    "id": "123456789012345678",
    "username": "my_awesome_bot",
    "discriminator": "0001",
    "avatar": null,
    "flags": 0
  }
}

Get Gateway Info

Verify your bot can access the Gateway:

curl -H "Authorization: Bot {bot_token}" \
  https://api.fluxer.app/v1/gateway/bot

Response:

{
  "url": "wss://gateway.fluxer.app",
  "shards": 1,
  "session_start_limit": {
    "total": 1000,
    "remaining": 999,
    "reset_after": 14400000,
    "max_concurrency": 1
  }
}

Next Steps

Now that you have a bot account and token:

Connect to Gateway

Establish a WebSocket connection to receive real-time events

Send Your First Message

Use the REST API to send messages

Handle Commands

Process user commands and interactions

Set Up Webhooks

Configure webhooks for event delivery

Troubleshooting

Error: Unclaimed accounts cannot create applications

You must verify your email address before creating bot applications. Check your inbox for a verification email.

Error: Bot user generation failed

This occurs when the username generation exhausts available discriminators (rare). The system will retry with random usernames up to 100 times. Contact support if this persists.

Bot token not working

Ensure you’re using the correct authorization header format:

Authorization: Bot {token}

Not Bearer, but Bot as the prefix.

Cannot change bot discriminator

Bot discriminators are automatically assigned and cannot be directly changed. Changing the username will trigger a new discriminator assignment.

Security Best Practices

Use Environment Variables

Never hardcode tokens in your source code. Use environment variables or secure secret management systems.

Rotate Tokens Regularly

Set up a schedule to rotate bot tokens (e.g., every 90 days) to minimize the impact of potential compromises.

Monitor Token Usage

Log token usage and set up alerts for unusual activity patterns.

Use Separate Bots

Maintain separate bot applications for development, staging, and production environments.

Implement Proper Error Handling

Ensure tokens are never leaked in error messages, logs, or stack traces.

Get Started

Core Features

Self-Hosting

Bot Development

WebSocket Gateway

Topics

Resources

​Overview

​Prerequisites

​Creating an Application

​Using the API

​Response

​Understanding Bot Tokens

​Token Format

​Token Storage

​Bot User Generation

​Username Examples

​Bot User Properties

​Customizing Your Bot

​Update Bot Profile

​Bot Flags

​Managing Your Bot

​Rotating Bot Token

​Listing Your Applications

​Deleting Your Bot

​Inviting Your Bot

​OAuth2 Authorization URL

​Permission Calculation

​Common Permission Sets

​Testing Your Bot

​Verify Token

​Get Gateway Info

​Next Steps

Connect to Gateway

Send Your First Message

Handle Commands

Set Up Webhooks

​Troubleshooting

​Security Best Practices

Build docs developers (and LLMs) love

Overview

Prerequisites

Creating an Application

Using the API

Response

Understanding Bot Tokens

Token Format

Token Storage

Bot User Generation

Username Examples

Bot User Properties

Customizing Your Bot

Update Bot Profile

Bot Flags

Managing Your Bot

Rotating Bot Token

Listing Your Applications

Deleting Your Bot

Inviting Your Bot

OAuth2 Authorization URL

Permission Calculation

Common Permission Sets

Testing Your Bot

Verify Token

Get Gateway Info

Next Steps

Troubleshooting

Security Best Practices