Skip to main content

​
What are Fluxer Bots?

Bots are automated users that can interact with your Fluxer server programmatically. They can respond to messages, manage channels, moderate content, provide information, and integrate with external services.

​
Why Build a Bot?

Fluxer bots enable you to:
  • Automate Tasks: Schedule messages, manage roles, and perform routine operations
  • Moderate Communities: Filter content, enforce rules, and manage member behavior
  • Integrate Services: Connect external APIs, databases, and third-party platforms
  • Enhance User Experience: Provide custom commands, interactive features, and rich content
  • Gather Analytics: Track metrics, generate reports, and monitor server activity

​
Common Use Cases

Moderation Bots

Automatically filter spam, enforce server rules, and manage user warnings

Utility Bots

Provide helpful commands for server information, user profiles, and more

Music Bots

Stream audio, manage playlists, and control playback in voice channels

Integration Bots

Connect to GitHub, Sentry, and other services via webhooks

​
How Bots Work

​
Bot Users

When you create a bot application, Fluxer automatically generates a bot user account. This account:
  • Has a unique user ID derived from the application ID
  • Can be invited to guilds via OAuth2 authorization
  • Receives real-time events through the WebSocket Gateway
  • Can perform API actions using a bot token
Bot users are flagged with bot: true in API responses and display with a bot badge in clients.

​
Authentication Flow

Bots authenticate using a bot token with the following format: 
{application_id}.{secret}
Example: 
123456789012345678.dGhpcyBpcyBhIHNlY3JldCB0b2tlbiBleGFtcGxl
Never share your bot token publicly. It provides full access to your bot account.

​
Bot Lifecycle

  1. Create Application: Register your bot in the developer portal
  2. Generate Token: Obtain authentication credentials
  3. Invite to Guild: Authorize the bot with required permissions
  4. Connect to Gateway: Establish WebSocket connection for real-time events
  5. Handle Events: Process messages, member joins, and other activities
  6. Execute Commands: Respond to user interactions and perform actions

​
Bot Capabilities

​
API Access

Bots have access to most REST API endpoints:
  • Send and manage messages
  • Create and modify channels
  • Manage roles and permissions
  • Access guild and member information
  • Create webhooks for event notifications

​
Gateway Events

Bots receive real-time events including:
  • MESSAGE_CREATE - New messages in accessible channels
  • GUILD_MEMBER_ADD - New members joining guilds
  • VOICE_STATE_UPDATE - Voice channel state changes
  • INTERACTION_CREATE - Slash command and component interactions
See Gateway Connection for details.

​
Permissions

Bots use the same permission system as regular users:
  • Request specific permissions during OAuth2 authorization
  • Permissions are granted via roles in each guild
  • Check permissions before attempting privileged operations
Request only the minimum permissions your bot needs to function.

​
Bot Types

​
Public vs Private Bots

Public Bots (bot_public: true):
  • Can be invited by anyone with the invite link
  • Suitable for community bots and public services
  • Default setting for new applications
Private Bots (bot_public: false):
  • Can only be invited by the bot owner
  • Ideal for personal projects or private servers
  • More control over bot distribution

​
Friendly Bots

Bots can be marked with the FRIENDLY_BOT flag to:
  • Automatically accept friend requests from users
  • Enable direct messaging without prior friend requests
  • Useful for support bots and user-facing services
// Flag values from UserConstants
const FRIENDLY_BOT = 1n << 20n;
const FRIENDLY_BOT_MANUAL_APPROVAL = 1n << 21n;

​
Rate Limits

Bots are subject to rate limiting to ensure platform stability:
  • Global Rate Limit: 50 requests per second across all endpoints
  • Per-Route Limits: Vary by endpoint (e.g., 5 messages per 5 seconds per channel)
  • Gateway Identify: 1 connection per 5 seconds
Implement exponential backoff and respect X-RateLimit-* headers in API responses.

​
Getting Started

Ready to build your first bot? Follow these guides:

Creating a Bot

Set up a bot application and get your token

Gateway Connection

Connect to the WebSocket Gateway for real-time events

Commands & Interactions

Handle user commands and interactions

Webhooks

Use webhooks for event delivery and integrations

​
Best Practices

​
Security

  • Store bot tokens in environment variables, never in source code
  • Rotate tokens regularly using the API
  • Use separate bots for development and production environments
  • Implement proper error handling to avoid token leaks in logs

​
Performance

  • Cache frequently accessed data (guild info, member lists)
  • Use bulk operations when possible (bulk delete messages)
  • Implement connection pooling for database access
  • Handle rate limits gracefully with retry logic

​
User Experience

  • Provide clear command documentation and help messages
  • Use descriptive error messages when commands fail
  • Respond quickly to user interactions (within 3 seconds)
  • Implement confirmation prompts for destructive actions

​
Resources

API Reference

Complete API endpoint documentation

Gateway Events

Real-time event reference

OAuth2 Flow

Bot authorization and permissions

Rate Limits

Understanding and handling rate limits

​
Next Steps

Now that you understand the basics of Fluxer bots, continue to Creating a Bot to build your first application.

Build docs developers (and LLMs) love

Get started for freeTalk to us