Reference

Preamble

You should be somewhat familiar with the Quarkus framework before creating your Quarkus Discord bot. Quarkus has extensive documentation at https://quarkus.io/guides to help you get started.

Additionally, the Discord4J documentation and the Discord API Gateway event documentation are essential resources to have on hand.

Discord4J uses Project Reactor as its reactive framework instead of Mutiny, the reactive layer most Quarkus users will be familiar with. For this reason, reactive listener methods support returning Mono instead of Uni and Flux instead of Multi, but you can still convert your Reactor streams into Mutiny streams if you want.

The Choosing an Operator guide might be useful to you if you don’t want to convert your streams.

Events

Listening to events

To listen to Gateway events, simply declare a method with an event type parameter and annotate it with @GatewayEvent. The method can return Mono, Uni, Flux, or Multi.

Here’s an example of an imperative listener method:

class AddReaction {
    Mono<Void> onMessageCreate(@GatewayEvent MessageCreateEvent event) {
        return event.getMessage().addReaction(ReactionEmoji.of("🤖"));
    }
}

A few details about Gateway listener methods:

  • The declaring class and method can be public, protected, or package private

  • The declaring class has to be a concrete class

  • The method should be concrete

  • The annotated event must be the first parameter

Event types

All the currently supported event types can be found by checking out the subclasses of the Event class.

Bean injection

Gateway client

You can inject a GatewayDiscordClient bean that exposes high level methods to manage Discord resources via REST, access the underlying entity cache, and manage your bot’s connection to the Gateway and Voice Gateway.

This usually isn’t necessary as each Discord4J event exposes the Gateway client via Event#getClient(), and you can manage most resources directly from its corresponding entity instance.

An example:

@ApplicationScoped
class MyBean {
    @Inject
    GatewayDiscordClient gateway;

    // do something with gateway
}

Into methods

Any method that listens to a Gateway event can inject beans as additional parameters.

For example:

class DeletePersistentMessage {
    Mono<Void> onMessageDelete(@GatewayEvent MessageDeleteEvent event, EntityManager em) {
        // do something with em
    }
}

Metrics

If your Quarkus app uses a metrics extension like Micrometer or SmallRye Metrics, you can enable metrics collection for your bot exposed at the /q/metrics endpoint by setting the configuration property quarkus.discord4j.metrics.enabled to true.

Currently, metrics are collected for the number of servers your bot is in and the number of voice channels your bot is in.

Health check

A readiness health check for your bot is automatically exposed at the /q/health/ready endpoint if your Quarkus app depends on SmallRye Health. All of your bot’s shards will be checked and the health status will be DOWN if any shard isn’t connected.

You can disable the health check by setting quarkus.discord4j.health.enabled to false.

Native executable

You can package your Discord bot into a native executable with GraalVM or Mandrel to reduce its memory footprint and speed up its boot time. See the Building a native executable guide for more information.

Configuration

You can configure the following properties:

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.discord4j.health.enabled

Whether a health check should be published for the Gateway clients managed by this extension if the quarkus-smallrye-health extension is present

Environment variable: QUARKUS_DISCORD4J_HEALTH_ENABLED

boolean

true

quarkus.discord4j.metrics.enabled

Whether metrics should be collected for the Gateway clients managed by this extension if the quarkus-micrometer or quarkus-smallrye-metrics extension is present

Environment variable: QUARKUS_DISCORD4J_METRICS_ENABLED

boolean

false

quarkus.discord4j.global-commands.overwrite-on-start

Whether to serialize and register the JSON files found in path as global commands on startup.

Environment variable: QUARKUS_DISCORD4J_GLOBAL_COMMANDS_OVERWRITE_ON_START

boolean

false

quarkus.discord4j.global-commands.path

The path to the JSON files of the global commands.

Environment variable: QUARKUS_DISCORD4J_GLOBAL_COMMANDS_PATH

string

META-INF/commands

quarkus.discord4j.global-commands.delete-missing

Whether to delete registered global commands whose JSON representation is not found in path.

Environment variable: QUARKUS_DISCORD4J_GLOBAL_COMMANDS_DELETE_MISSING

boolean

false

quarkus.discord4j.token

The bot token used to authenticate to the Discord API.

Environment variable: QUARKUS_DISCORD4J_TOKEN

string

required

quarkus.discord4j.presence.status

The status of the bot.

Environment variable: QUARKUS_DISCORD4J_PRESENCE_STATUS

unknown, online, do-not-disturb, idle, invisible, offline

quarkus.discord4j.enabled-intents

The Gateway intents that should be enabled. Specific Gateway intents are required to receive certain Gateway events. Non-privileged intents will be enabled by default.

Environment variable: QUARKUS_DISCORD4J_ENABLED_INTENTS

list of Intent

quarkus.discord4j.entity-retrieval-strategy

The strategy to use for retrieving Discord entities. Default is cache-fallback-rest.

Environment variable: QUARKUS_DISCORD4J_ENTITY_RETRIEVAL_STRATEGY

EntityRetrievalStrategy

quarkus.discord4j.sharding.count

The number of shards that this bot should be split into.

Environment variable: QUARKUS_DISCORD4J_SHARDING_COUNT

int

quarkus.discord4j.sharding.indices

Which shards from the configured number of shards that this bot will receive events from. The bot will receive events from all specified shards by default.

Environment variable: QUARKUS_DISCORD4J_SHARDING_INDICES

list of int

0

quarkus.discord4j.sharding.max-concurrency

The number of shards that this bot will concurrently identify to the Gateway.

=== This property should only ever be configured if the bot is allowed to use very large sharding. Otherwise, the bot will incur a rate limit when identifying to the Gateway. ===

Environment variable: QUARKUS_DISCORD4J_SHARDING_MAX_CONCURRENCY

int

quarkus.discord4j.guild-commands."guild-commands".overwrite-on-start

Whether to serialize and register the JSON files found in path as commands in this guild on startup.

Environment variable: QUARKUS_DISCORD4J_GUILD_COMMANDS__GUILD_COMMANDS__OVERWRITE_ON_START

boolean

false

quarkus.discord4j.guild-commands."guild-commands".path

The path to the JSON files of the guild commands. By default, the path is <global-commands.path> + / + <config-name>

Environment variable: QUARKUS_DISCORD4J_GUILD_COMMANDS__GUILD_COMMANDS__PATH

string

quarkus.discord4j.guild-commands."guild-commands".delete-missing

Whether to delete commands registered in this guild whose JSON representation is not found in path.

Environment variable: QUARKUS_DISCORD4J_GUILD_COMMANDS__GUILD_COMMANDS__DELETE_MISSING

boolean

false

quarkus.discord4j.guild-commands."guild-commands".guild-id

The ID of the guild.

Environment variable: QUARKUS_DISCORD4J_GUILD_COMMANDS__GUILD_COMMANDS__GUILD_ID

long

0l

Activity configuration This configuration section is optional

Type

Default

quarkus.discord4j.presence.activity.type

The type of activity.

Environment variable: QUARKUS_DISCORD4J_PRESENCE_ACTIVITY_TYPE

unknown, playing, streaming, listening, watching, custom, competing

required

quarkus.discord4j.presence.activity.name

The name of the activity.

Environment variable: QUARKUS_DISCORD4J_PRESENCE_ACTIVITY_NAME

string

required

quarkus.discord4j.presence.activity.url

The YouTube or Twitch URL of the stream, if the activity type is streaming.

Environment variable: QUARKUS_DISCORD4J_PRESENCE_ACTIVITY_URL

string