Bot options

This page lists every option a bot accepts: which gateway intents it subscribes to, what it keeps in cache, how it compresses traffic, how many shards it runs and what presence it shows. You already know how to create a bot and log it in (see Starting a bot) and have a token at hand.

How options work

A bot goes through two phases. Between a new discord bot and login it is configuring: every property below can be set, and reading one gives back what you configured. Once login runs, the bot is running and its connection is built with the options it had at that moment. The connection options (intents, member cache policy, cache flags, compression, shard count, and the token) are build-time only: setting one on a running bot does nothing to the connection and prints a readable error in the console instead. The two presence options (activity and online status) are live: set them before login to start with them, or on a running bot to change them on the fly.

options:
    token: "YOUR-TOKEN"

command /startbot <text>:
    trigger:
        shutdown the bot named "my-bot"
        set {_bot} to a new discord bot
        set token of {_bot} to {@token}
        set intents of {_bot} to "default intents"
        set member cache policy of {_bot} to "all"
        set cache flags of {_bot} to "activity, voice_state, online_status"
        set compression of {_bot} to "zlib"
        set activity of {_bot} to "with Skript"
        set online status of {_bot} to dnd
        login {_bot} as "my-bot"

The leading shutdown makes the command reload-safe: re-running it replaces the bot named "my-bot" instead of logging a second copy. Every set line between the creation and the login is optional; a bot with only a token logs in with the defaults from the table below.

Options

Each property is read with <property> of {_bot} and written with set <property> of {_bot} to <value>. Text values are case-insensitive; names that contain a space can be written with a space or an underscore (voice state or voice_state).

Intents

Gateway intents tell Discord which groups of events your bot wants to receive. A bot without the guild_messages intent never sees a message sent in a guild, whatever your script listens to. The value is a list of intent names separated by commas, or a shortcut; setting it replaces the whole set.

set intents of {_bot} to "guild_messages, message_content, guild_members"

Two shortcuts exist, and both can be mixed with names to add a few intents on top:

• "default intents" (or "default"): the set a fresh bot uses, marked in the table below.
• "all": every intent JDA knows.

set intents of {_bot} to "default intents, guild_message_polls"

Privileged intents are only delivered if they are switched on for your application under Bot → Privileged Gateway Intents on the Developer Portal. Reading intents of {_bot} returns the enabled names in upper case, separated by commas.

Caching

Two properties decide what the bot keeps in memory, and both go before login. The member cache policy says which members stay cached once Discord has sent them. The cache flags list which extra pieces of data are cached on top of the entities themselves. Setting either property replaces its previous value.

set member cache policy of {_bot} to "online"
set cache flags of {_bot} to "default, emoji"

Cache flags accept the names below, or one of three shortcuts: "default" stands for activity, voice_state and online_status; "all" enables every flag; "none" clears the list. A flag only fills up when its intent is enabled.

Reading either property returns the configured names in upper case, so a bot you never configured reads back "DEFAULT" for its policy and an empty text for its flags.

The compression property belongs to the same group: "zlib" (the default) compresses the gateway traffic, "none" disables it. Leave it alone unless you are debugging the raw connection.

Sharding

A shard is one gateway connection; Discord requires bots in 2,500 guilds or more to split their guilds across several. The shard count property picks how many connections the bot opens: -1 (the default) asks Discord for its recommended count, 1 forces a single connection and any number of 2 or more forces that many. The recommended shard count expression is a readable name for -1.

set shard count of {_bot} to recommended shard count

Sharding is invisible to your scripts. Lifecycle events such as on ready and on bot shutdown fire once per bot, when its last shard comes up or goes down, not once per shard; seen by filters and the properties of the bot work the same whatever the count. Once the bot runs, shard count of {_bot} returns the real shard total and running shards tells how many of them are currently connected:

on ready seen by "my-bot":
    send "%running shards of event-bot%/%shard count of event-bot% shards up" to console

Keep -1 unless you know the number you need: Discord decides how many shards a bot may open, and a forced count it does not accept fails at login.

Presence

The activity sets the text shown under the bot's name as Playing <text>; an empty text removes it. The online status picks the presence dot: online, idle, dnd (do not disturb) or invisible. Unlike the connection options, both are live: setting them before login gives the bot its starting presence, and setting them on a running bot updates every shard immediately.

on ready seen by "my-bot":
    set activity of event-bot to "in %guild count of event-bot% guilds"
    set online status of event-bot to idle

The value of online status is a DiSky type, not a text: write dnd, not "dnd". The same property reads the presence of a member, but is only writable on a bot.

Errors you may see