Skip to main content
Client is the central entry point of the library. It holds the cache, REST client, WebSocket connection, and event handlers.

​
ClientOptions

Passed to Client::new(options).
FieldTypeDefaultDescription
intentsu640Gateway intents. Fluxer does not use intents - always 0.
presenceOption<GatewayPresenceUpdateSendData>NoneInitial bot presence on connect.
restOption<RestOptions>NoneREST client options. Defaults are used when None.
gateway_versionOption<String>NoneGateway version. Defaults to "1" when None.
wait_for_guildsboolfalseIf true, the Ready event is delayed until all GUILD_CREATE events are received.
cacheCacheSizeLimitsall NonePer-entity cache size limits.

​
CacheSizeLimits

FieldTypeDescription
guildsOption<usize>Maximum number of guilds in cache.
channelsOption<usize>Maximum number of channels in cache.
usersOption<usize>Maximum number of users in cache.
membersOption<usize>Maximum number of members (across all guilds) in cache.
When a limit is exceeded, the oldest entries are evicted automatically after each GUILD_CREATE. If a limit is None, the cache is unbounded.

​
Client

​
Public fields

FieldTypeDescription
restRestREST client. Arc-based, cloning is cheap.
guildsDashMap<String, Guild>Guild cache.
channelsDashMap<String, Channel>Channel cache.
usersDashMap<String, User>User cache.
membersDashMap<String, DashMap<String, GuildMember>>Member cache: guild_id → user_id → GuildMember.

​
Methods

​
Client::new

pub fn new(options: ClientOptions) -> Self
Creates the client. REST is initialized immediately. The WebSocket connection is not established until login is called.

​
on

pub fn on<F, Fut>(&mut self, event: &str, callback: F)
where
    F: Fn(Value) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = ()> + Send + 'static,
Registers a raw event handler by name. Data is delivered as serde_json::Value without type information. String constants for event names are available via Events::MESSAGE_CREATE, etc. Multiple handlers can be registered for the same event - all are called in order. 
client.on(Events::MESSAGE_CREATE, |data| async move {
    println!("{data}");
});

​
on_typed

pub fn on_typed<F, Fut>(&mut self, callback: F)
where
    F: Fn(DispatchEvent) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = ()> + Send + 'static,
Registers a typed event handler. Receives a DispatchEvent - an enum with concrete variants for each event. This is the preferred way to handle events. 
client.on_typed(move |event| {
    Box::pin(async move {
        match event {
            DispatchEvent::Ready => {
                tracing::info!("ready");
            }
            DispatchEvent::MessageCreate { message, .. } => {
                println!("{}", message.content);
            }
            _ => {}
        }
    })
});
The closure must return Box::pin(async move { ... }). All values used inside must be cloned before entering the closure, as it is called repeatedly.

​
login

pub async fn login(&mut self, token: impl Into<String>) -> crate::Result<()>
Sets the token in REST, connects to Gateway, and starts the WebSocket event loop. Blocks execution until the connection is dropped or destroy is called.

​
user

pub fn user(&self) -> Option<&ClientUser>
Returns the bot’s own user data received in the READY event. Returns None before login.

​
is_ready / ready_at

pub fn is_ready(&self) -> bool
pub fn ready_at(&self) -> Option<std::time::Instant>
is_ready - true after READY is received and (if wait_for_guilds: true) all GUILD_CREATE events have been processed. ready_at - the instant the ready flag was set.

​
send_to_gateway / send_to_shard

pub async fn send_to_gateway(&self, payload: Value)
pub async fn send_to_shard(&self, shard_id: u32, payload: Value) -> Result<(), String>
Sends a raw JSON payload to Gateway. send_to_gateway broadcasts to all shards. send_to_shard targets a specific shard. 
let payload = serde_json::json!({
    "op": 3,
    "d": {
        "status": "online",
        "afk": false,
        "since": null,
        "activities": []
    }
});
client.send_to_gateway(payload).await;

​
create_message_collector / create_reaction_collector

pub fn create_message_collector(&mut self, options: MessageCollectorOptions) -> MessageCollector
pub fn create_reaction_collector(&mut self, options: ReactionCollectorOptions) -> ReactionCollector
Creates a collector for gathering messages or reactions. See Collectors for details.

​
fetch_instance

pub async fn fetch_instance(&self) -> crate::Result<Value>
Returns information about the Fluxer instance (GET /instance).

​
destroy

pub fn destroy(&mut self)
Terminates the WebSocket connection and resets client state. After calling this, login will return or error out.

​
Managers

Managers are thin wrappers that combine cache and REST. They are constructed on the fly from references to client fields. They are not stored as fields on Client - create them right before use. 
let gm = client.guilds(&client.rest);
let cm = client.channels(&client.rest);
let um = client.users(&client.rest);

​
GuildManager

MethodDescription
get(id)Returns a guild from cache. None if not present.
fetch(id)Fetches the guild via REST, updates cache.
resolve(id)Returns from cache, falls back to fetch.

​
ChannelManager

MethodDescription
get(id)Returns a channel from cache.
fetch(id)Fetches the channel via REST, updates cache.
resolve(id)Cache → REST fallback.
send(channel_id, body)Sends a message to a channel without going through the Channel structure.
fetch_message(channel_id, message_id)Fetches a message by ID.

​
UsersManager

MethodDescription
get(id)Returns a user from cache.
fetch(id)Fetches the user via REST.
resolve(id)Cache → REST fallback.
fetch_with_profile(id)Returns ApiProfileResponse - extended profile data.

​
Error handling

All async client methods return crate::Result<T>, where Error is:
VariantDescription
Error::ClientNotReadyMethod called before login completed.
Error::InvalidTokenToken rejected by Gateway.
Error::AlreadyLoggedInlogin called more than once.
Error::Api(FluxerApiError)API returned a structured error with code and message.
Error::Http(HttpError)HTTP error without a recognized API response body.
Error::RateLimit(RateLimitError)Rate limit exhausted after all retry attempts.
Error::Rest(RestError)Network or JSON error.
Error::WebSocket(String)WebSocket connection error.
Error::Other(String)Miscellaneous errors.