Skip to main content
The Fluxer Gateway is a WebSocket-based real-time API that enables clients to receive events about guilds, messages, presence updates, and more. It provides bidirectional communication between clients and the Fluxer platform.

​
Key Features

Real-time Events

Receive instant updates for messages, guild changes, and user presence

Compression Support

Optional zstd-stream compression for reduced bandwidth usage

Session Management

Resume interrupted sessions without missing events

Rate Limiting

Built-in rate limiting to prevent abuse (120 events/60s)

​
Gateway URL

Connect to the Gateway using the WebSocket URL obtained from the /gateway/bot endpoint: 
wss://gateway.fluxer.example/?v=1&encoding=json

​
Query Parameters

ParameterTypeRequiredDescription
vintegerYesGateway API version (currently 1)
encodingstringNoMessage encoding format (json, default)
compressstringNoCompression algorithm (zstd-stream or none)
The Gateway currently supports version 1 only. Connecting without v=1 will result in close code 4012 (Invalid API Version).

​
Connection Flow

​
Message Format

All Gateway messages follow this JSON structure: 
{
  "op": 2,
  "d": {
    "token": "your.auth.token",
    "properties": {
      "os": "linux",
      "browser": "fluxer-client",
      "device": "fluxer-client"
    }
  }
}

​
Message Fields

FieldTypeDescription
opintegerOpcode identifying the message type
dmixedEvent data (type varies by opcode)
sintegerSequence number (for dispatch events only)
tstringEvent name (for dispatch events only)

​
Configuration Constants

The Gateway enforces several limits and intervals defined in the source code:
These values are extracted from fluxer_gateway/src/utils/constants.erl.
ConstantValueDescription
Heartbeat Interval41,250 msTime between heartbeat requests
Heartbeat Timeout45,000 msMaximum time to wait for heartbeat ACK
Max Payload Size4,096 bytesMaximum size of incoming messages
Rate Limit Window60,000 msTime window for rate limiting
Rate Limit Max Events120Maximum events per window
Guild Members Rate Limit3 requests/10sRate limit for REQUEST_GUILD_MEMBERS

​
Connection Requirements

1

Obtain Gateway URL

Call GET /gateway/bot to get the WebSocket URL and session limits
2

Establish WebSocket Connection

Connect with query parameters: v=1&encoding=json
3

Receive Hello

Wait for the Hello message (opcode 10) containing heartbeat interval
4

Start Heartbeating

Begin sending heartbeats at the specified interval
5

Identify or Resume

Send Identify (opcode 2) for new sessions or Resume (opcode 6) for reconnection
6

Receive Ready

Process the Ready event containing user, guild, and session data

​
Rate Limiting

The Gateway implements two types of rate limiting:

​
General Rate Limit

Sending more than 120 events within 60 seconds will result in immediate disconnection with close code 4008 (Rate Limited).
Rate-limited operations:
  • Heartbeat (opcode 1)
  • Identify (opcode 2)
  • Presence Update (opcode 3)
  • Voice State Update (opcode 4)
  • Resume (opcode 6)
  • Lazy Request (opcode 14)

​
Opcode-Specific Limits

REQUEST_GUILD_MEMBERS (opcode 8):
  • Maximum 3 requests per 10 seconds
  • Exceeding this limit results in close code 4008
VOICE_STATE_UPDATE (opcode 4):
  • Maximum 10 updates per second
  • Exceeding this limit queues updates (max queue: 64)
  • Queue is processed at 100ms intervals

​
Client IP Detection

The Gateway extracts the client’s real IP address from the X-Forwarded-For header when present, with support for:
  • IPv4 addresses (with or without port)
  • IPv6 addresses (bracketed or unbracketed)
  • Multiple forwarded addresses (uses first valid entry)
This is implemented in gateway_handler.erl:extract_client_ip/1.

​
Next Steps

Connection Lifecycle

Learn about connecting, identifying, resuming, and heartbeating

Opcodes

Reference for all Gateway opcodes and their payloads

Events

Complete list of dispatch events you can receive

Close Codes

Understand disconnection reasons and how to handle them

Build docs developers (and LLMs) love

Get started for freeTalk to us