Client options

Reference for new Client(token, options). Every option is optional; defaults are shown.

Reference for new Client(token, options). Every option is optional; defaults are shown.

Core

Option	Default	Meaning
`intents`	`3243773` (all non-privileged)	Gateway intents. Array of `GatewayIntentBits`, array of name strings, or a raw number. See Intents.
`allowedMentions`	`{ everyone: false, roles: false, users: false, repliedUser: true }`	Default mention allowances for `createMessage` / `editMessage`. Overridable per call.
`autoreconnect`	`true`	Reconnect after gateway drops and failed `connect()` attempts.
`compress`	`true`	Gateway transport compression: `boolean \| 'zlib' \| 'zstd'`. `true` picks zstd-stream when the runtime supports it (Node >= 22.15), zlib-stream otherwise; all decompressed by the built-in `node:zlib` with zero native dependencies.
`connectionTimeout`	`30000`	Milliseconds to wait for the websocket handshake.
`defaultImageFormat`	`ImageFormat.JPEG`	Default format for avatar/icon URL helpers.
`defaultImageSize`	`128`	Default image size; a power of two between 16 and 4096.
`disableEvents`	`{}`	Map of `GatewayDispatchEvents` to `true` to skip parsing them entirely.
`gateway`	`{ transport: 'auto' }`	WebSocket transport: `{ transport?: 'auto' \| 'ws' \| 'native' }`. `'auto'` uses the runtime's built-in WebSocket when available and no custom `options.ws` is set, the optional `ws` package otherwise. `'ws'` requires `npm install ws`.
`getAllUsers`	`false`	Request every guild member on startup. Requires the `GuildMembers` intent and greatly delays `ready`.
`guildCreateTimeout`	`2000`	Milliseconds to wait for `GUILD_CREATE` after `READY` before firing `ready`.
`largeBotOptimizations`	`false`	Apply the maintained large-bot preset: `rest.fullErrorStacks: false`, `cache.guildEmojis: false`, `cache.guildStickers: false`, `cache.userSweepIntervalMs: 3600000`. Also enabled by `ATHENA_LARGE_BOT=1` in the environment; explicit options always win. The preset never touches semantics-changing knobs like `cache.transientMembers`.
`largeThreshold`	`250`	Member count above which a guild is "large" (members not sent inline). Discord caps at 250.
`messageLimit`	`100`	Max cached messages per channel. `0` keeps none.

Sharding

Option	Default	Meaning
`maxShards`	`1`	Shard count, or `"auto"` for Discord's recommendation.
`firstShardID` / `lastShardID`	-	Shard range for multi-process sharding.
`shards`	-	Explicit array of shard IDs to run.
`shardConcurrency`	`"auto"`	Shards that may identify in parallel.
`maxReconnectAttempts`	`Infinity`	Reconnect attempts before giving up.
`maxResumeAttempts`	`10`	Resume attempts before a fresh identify.
`reconnectDelay`	`(_, n) => (n + 1) ** 0.7 * 20000`	Delay (ms) before the next reconnect.

See Gateway and sharding.

REST (`options.rest`)

Option	Default	Meaning
`agent`	shared keep-alive agent	Custom HTTP(S) agent. Athena now defaults to a pooled keep-alive agent; supplying one overrides it.
`baseURL`	`/api/v10`	API base path.
`bucketSweepInterval`	`300000`	How often (ms) idle ratelimit buckets are swept from memory; `0` disables. A swept route relearns its limits from the next response's headers.
`domain`	`discord.com`	API domain.
`fullErrorStacks`	`true`	Capture a caller stack per request so REST errors point at your code. Set `false` on high-volume bots to skip that hot-path work; errors then capture a stack only on failure and still carry method, route, code, status, and message.
`https`	`true`	Set `false` for a plain-HTTP local proxy.
`requestTimeout`	`15000`	Max milliseconds a request may be in flight.
`latencyThreshold`	`30000`	Above this measured latency, Athena emits a `warn`.
`ratelimiterOffset`	`0`	Manual offset on ratelimit reset math.
`disableLatencyCompensation`	`false`	Turn off the latency-aware ratelimit adjustment.
`forceQueueing`	`false`	Hold all requests until `shardPreReady`.

See REST and ratelimits.

Caching (`options.cache`)

Two kinds of knobs, both opt-in:

Retention knobs: guildEmojis / guildStickers (keep raw emoji/sticker arrays per guild), transientMembers (cache members/users seen only via reactions, typing, messages, and interactions), userSweepIntervalMs (periodically evict users referenced by nothing).
Per-cache factory overrides for users, guilds, privateChannels, members, channels, threads, roles, voiceStates, stageInstances, and messages, plus remoteStore for cluster-shared caching.

Unset values keep the default unbounded in-memory store, so leaving this undefined keeps current behaviour. See Caching and memory and Scaling to millions.

WebSocket (`options.ws`)

Raw ws client options (headers, agent, TLS). Athena copies rest.agent into ws.agent if unset. Setting this selects the optional ws package as the transport, so run npm install ws first.

Default presence

Set status after construction, before or during ready:

client.presence = {
  status: PresenceUpdateStatus.Online,
  afk: false,
  since: null,
  activities: [{ name: 'with Athena', type: ActivityType.Playing }]
};

Client options

Core#

Sharding#

REST (options.rest)#

Caching (options.cache)#