Skip to main content

Overview

This guide will walk you through creating a bot account and making your first authenticated API request to Fluxer. You’ll learn how to:
  • Create an OAuth2 application with a bot user
  • Obtain a bot token for authentication
  • Make authenticated API requests
  • Understand response formats
This quickstart uses the hosted Fluxer instance at api.fluxer.app. If you’re self-hosting, replace the base URL with your instance.

Prerequisites

Before starting, you need:
  • A Fluxer account (create one at web.fluxer.app)
  • curl or another HTTP client (examples use curl)
  • A text editor for storing your bot token
Never share your bot token publicly or commit it to version control. Treat it like a password.

Step 1: Create an OAuth2 Application

Bot accounts in Fluxer are created through OAuth2 applications. Each application automatically gets an associated bot user.
1

Navigate to User Settings

  1. Open Fluxer (web or desktop)
  2. Click your avatar in the bottom-left
  3. Select User Settings
  4. Navigate to Applications in the sidebar
2

Create New Application

Click New Application and provide:
  • Name: Your bot’s display name (e.g., “My First Bot”)
  • Redirect URIs: Leave empty for now (only needed for OAuth2 flows)
Click Create to generate your application.
3

Copy Bot Token

Your application details will show:
  • Application ID (Client ID)
  • Client Secret
  • Bot Token (under the “Bot” section)
The bot token is only shown once. Copy it immediately and store it securely.
Click Copy next to the bot token and save it somewhere safe.

Application Structure

When you create an application, Fluxer automatically provisions:
  1. OAuth2 Application - Used for authorization flows
  2. Bot User Account - A special user account for programmatic access
  3. Client Credentials - ID and secret for OAuth2 client authentication

Step 2: Make Your First API Call

Let’s verify your bot token by fetching the bot’s user information.

Fetch Current User

curl -X GET https://api.fluxer.app/api/v1/users/@me \
  -H "Authorization: Bot YOUR_BOT_TOKEN"
{
  "id": "1234567890123456789",
  "username": "my_first_bot",
  "discriminator": "0001",
  "global_name": "My First Bot",
  "avatar": null,
  "bot": true,
  "system": false,
  "mfa_enabled": false,
  "verified": true,
  "email": null,
  "flags": 0,
  "premium_type": 0,
  "public_flags": 0
}
Key fields:
  • id: Snowflake ID of your bot user
  • username: Bot’s username
  • bot: Always true for bot accounts
  • verified: Email verification status (always true for bots)

Understanding Authentication Headers

Bot authentication uses the Authorization header with the format:
Authorization: Bot <token>
  • Prefix: Must be Bot (case-sensitive)
  • Token: Your bot token from the application settings
  • Separator: Single space between prefix and token
Do not use Bearer prefix for bot tokens. That’s for OAuth2 access tokens only.

Step 3: Send a Message

Now let’s send a message to a channel. You’ll need a channel ID where your bot has access.
Bot accounts can only access channels in guilds where they’ve been added. Initially, your bot won’t be in any guilds.

Add Bot to a Guild

Before sending messages, add your bot to a guild (server):
1

Generate OAuth2 URL

Use this URL format (replace CLIENT_ID with your Application ID):
https://fluxer.app/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=0
You can specify permissions as a bitfield. For basic message sending, use 2048 (Send Messages).
2

Authorize Bot

  1. Open the URL in your browser
  2. Select a guild to add the bot to
  3. Review permissions and click Authorize
Your bot will now appear in the guild’s member list.

Send a Message

Once your bot is in a guild, send a message to a channel:
curl -X POST https://api.fluxer.app/api/v1/channels/CHANNEL_ID/messages \
  -H "Authorization: Bot YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from my bot!"
  }'
{
  "id": "9876543210987654321",
  "channel_id": "1234567890123456789",
  "author": {
    "id": "1234567890123456789",
    "username": "my_first_bot",
    "discriminator": "0001",
    "avatar": null,
    "bot": true
  },
  "content": "Hello from my bot!",
  "timestamp": "2026-03-04T12:34:56.789Z",
  "edited_timestamp": null,
  "tts": false,
  "mention_everyone": false,
  "mentions": [],
  "mention_roles": [],
  "attachments": [],
  "embeds": [],
  "reactions": [],
  "pinned": false,
  "type": 0
}

Step 4: Handle Errors

API requests can fail for various reasons. Always check the response status and handle errors gracefully.

Common Error Codes

Cause: Invalid or missing authentication tokenSolutions:
  • Verify your bot token is correct
  • Ensure the Authorization header uses Bot prefix
  • Check for extra whitespace in the token
{
  "code": "INVALID_TOKEN",
  "message": "Invalid authentication token"
}
Cause: Bot lacks permissions for the requested actionSolutions:
  • Check bot has required permissions in the guild
  • Verify bot is a member of the guild
  • Review channel-specific permission overrides
{
  "code": "MISSING_PERMISSIONS",
  "message": "Missing permission: SEND_MESSAGES"
}
Cause: Rate limit exceededSolutions:
  • Respect the Retry-After header (in seconds)
  • Implement exponential backoff
  • Cache responses when possible
{
  "message": "Rate limit exceeded",
  "retry_after": 5.234
}
See Rate Limits for detailed information.

Error Handling Example

async function sendMessage(channelId, content) {
  const response = await fetch(
    `https://api.fluxer.app/api/v1/channels/${channelId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bot ${process.env.BOT_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ content })
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 429) {
      // Rate limited - wait and retry
      const retryAfter = error.retry_after * 1000;
      console.log(`Rate limited. Retrying after ${retryAfter}ms`);
      await new Promise(resolve => setTimeout(resolve, retryAfter));
      return sendMessage(channelId, content); // Retry
    }
    
    throw new Error(`API Error: ${error.message}`);
  }
  
  return response.json();
}

Step 5: Connect to the Gateway (Optional)

For real-time events (new messages, reactions, presence updates), connect to the WebSocket Gateway.
The Gateway is optional. If you only need to make API calls (e.g., send messages on a schedule), the REST API is sufficient.

Gateway Overview

  1. Connect to wss://gateway.fluxer.app
  2. Send identification with your bot token
  3. Receive events as they happen
  4. Send heartbeats to maintain the connection
See the Gateway documentation for complete connection details.

Quick Gateway Example

const WebSocket = require('ws');

const ws = new WebSocket('wss://gateway.fluxer.app');

ws.on('open', () => {
  // Send identify payload
  ws.send(JSON.stringify({
    op: 2, // IDENTIFY
    d: {
      token: `Bot ${process.env.BOT_TOKEN}`,
      intents: 513, // GUILDS | GUILD_MESSAGES
      properties: {
        os: 'linux',
        browser: 'my-bot',
        device: 'my-bot'
      }
    }
  }));
});

ws.on('message', (data) => {
  const payload = JSON.parse(data);
  
  if (payload.op === 0) { // DISPATCH
    console.log('Event:', payload.t, payload.d);
  } else if (payload.op === 10) { // HELLO
    // Start heartbeat interval
    const heartbeatInterval = payload.d.heartbeat_interval;
    setInterval(() => {
      ws.send(JSON.stringify({ op: 1, d: null }));
    }, heartbeatInterval);
  }
});

Next Steps

Congratulations! You’ve created a bot and made your first API calls. Here’s what to explore next:

Authentication Deep Dive

Learn about OAuth2, user tokens, and session management

API Reference

Browse all available endpoints and resources

Gateway Guide

Connect to real-time events via WebSocket

Bot Examples

Explore bot patterns and best practices

Best Practices

  • Use environment variables (never hardcode)
  • Use secret management in production (AWS Secrets Manager, HashiCorp Vault)
  • Rotate tokens if compromised
  • Never commit tokens to version control
  • Respect Retry-After headers
  • Implement exponential backoff
  • Cache responses when possible
  • Use global rate limit buckets per resource
  • Sanitize user input before sending to API
  • Validate message content length (max 2000 characters)
  • Check file sizes before upload
  • Handle invalid IDs gracefully
  • Log API errors with context
  • Track rate limit hits
  • Monitor Gateway disconnections
  • Set up alerts for critical failures

Troubleshooting

Symptoms: 401 Unauthorized errorsSolutions:
  1. Verify token is copied correctly (no extra spaces)
  2. Ensure using Bot prefix, not Bearer
  3. Check token hasn’t been regenerated
  4. Confirm application still exists
Symptoms: 403 Forbidden errorsSolutions:
  1. Verify bot is in the guild
  2. Check bot has SEND_MESSAGES permission
  3. Review channel-specific permission overrides
  4. Ensure channel exists and bot can see it
Symptoms: 429 Too Many RequestsSolutions:
  1. Implement request queuing
  2. Add delays between bulk operations
  3. Cache responses to reduce API calls
  4. Review your bot’s request patterns

Support

Need help? Here are your options:

Build docs developers (and LLMs) love