Extensions

The extensions { } builder allows you to register extensions, and configure the bundled extensions. Third-party extensions often also add extension functions here.

Adding Extensions

ExtensibleBot(TOKEN) {
    // ...

    extensions {
        add(::MyExtension)
    }
}

add(...)

Register an extension to be loaded.

Arguments

builderType: () -> Extension

Callable object returning an Extension subtype. Usually, you'd pass a constructor here.

Help Extension

The help { } builder lets you configure the chat command help extension. This extension provides a general help chat command, which lists the commands a user can execute and gives them usage information.

Replacing The Extension

While Kord Extensions provides a standard help extension, you can build your own one implementing HelpProvider. Remember to disable the bundled extension if you decide to do this!

If you're developing a help extension meant for external use, you should disable the bundled extension in your configuration function:

fun ExtensionsBuilder.myHelpExtension() {
    help {
        enableBundledExtension = false
    }

    add(::MyHelpExtension)
}

Builders

check { ... }Receiver: Check<MessageCreateEvent>

Register a check that will apply to the help command and its subcommands.

colour { ... }Receiver: MessageCreateEventLambda Returns: Color

Set the callback that defines what Color to use for help embeds. The help command calls this on every execution, and the return value doesn't need to be consistent.

color { ... }Receiver: MessageCreateEventLambda Returns: Color

Like colour, but American.

Properties

var deleteInvocationOnPaginatorTimeoutType: BooleanDefault: false

Whether to delete the message that executed the help command when the paginator timeout expires.

var deletePaginatorOnTimeoutType: BooleanDefault: false

Whether to delete the help command's output message when the paginator timeout expires.

var enableBundledExtensionType: BooleanDefault: true

Whether to enable the bundled help extension

var paginatorTimeoutType: LongDefault: 60

How long since the user's last button press (or the command invocation) to wait before the help command's paginator times out and stops working, in seconds.

var pingInReplyType: BooleanDefault: true

Whether to mention/ping the user that ran the help command when responding.

Sentry Extension

The sentry { } builder lets you configure the Sentry integration, as well as the bundled feedback extension.

GDPR & Privacy

It is important to consider the privacy implications of submitting data to a third party. While Kord Extensions is not responsible if you decide to use this extension and something goes wrong, we understand how critical it is to get this right.

If you want to take the absolute safest route and prevent any personal data from being submitted to Sentry, you should use the predicate builder below to register a predicate that always returns false. Otherwise, we provide several best-effort options to help you avoid sending unnecessary data to Sentry.

For more information, see the [Sentry Integration page].

Builders

builder { ... }Lambda Returns: SentryAdapter

Register a callback that constructs and returns an alternative implementation of the SentryAdapter type, if needed.

dataTypeTransformer { ... }Receiver: SentryDataTypeBuilder

Register a Sentry data type transformer, allowing you to change the types of data that may be submitted to Sentry based on the given SentryCapture object.

Data type transformers are run before Kord Extensions adds the data defined in the SentryCapture object's properties to the relevant Sentry object.

Lambda Arguments

captureType: SentryCapture

The Sentry data capture object to operate on.

defaultDataTypes { ... }Receiver: SentryDataTypeBuilder

Configure the default data types that Kord Extensions is allowed to send to Sentry in breadcrumbs and exception reports.

For more information, see the GDPR & Privacy section above.

predicate { ... }Receiver: SentryCaptureLambda Returns: Boolean

Register a Sentry submission predicate, letting you filter what captured sets of data will be submitted to Sentry by returning false.

Kord Extensions runs these predicates before it submits the SentryCapture to Sentry. This the predicate runs after the relevant data is already sanitised and processed.

setup { ... }Receiver: SentryAdapter

Replace the bundled setup callback, which configures the SentryAdapter by calling its init function.

This should only be used if you need to precisely customise what data is passed to that function.

Functions

enableIfDSN(...)

Convenience function to conditionally set the Sentry DSN and enable the Sentry integration. This function is useful when combined with envOrNull to load the DSN from your bot's environment variables.

Arguments

sentryDSNType: String?

Your Sentry DSN, or null.

• If a String, enable and configure the Sentry integration with it.
• If null, do nothing.

Properties

Kord Extensions uses the following properties to configure its Sentry intgration, rather than the Sentry API.

var enableType: BooleanDefault: false

Whether to enable the Sentry integration.

var feedbackExtensionType: BooleanDefault: false

Whether to enable the Sentry feedback extension, which adds a feedback chat and slash command, and displays error IDs when your bot submits errors to Sentry.

Users can use the feedback command with these IDs to explain what they were doing.

var pingInReplyType: BooleanDefault: true

Whether to ping users in response to their feedback chat command uses.

var sampleRateType: DoubleDefault: 1.0

Portion of Sentry captures to submit to Sentry, as a percentage represented by a portion of one.

For example, 1.0 means everything, 0.1 means 10%, and so on.

Kord Extensions uses the following properties to configure the Sentry API directly. We only expose the most common options here, but you can use the setup builder to configure other options. For more information, see Sentry's documentation.

var debugType: BooleanDefault: devMode

Whether to enable Sentry's debug mode.

Defaults to your bot's devMode setting, as defined in the general settings.

var dsnType: String?Default: null

Your Sentry DSN, required to enable the integration.

var distributionType: String?Default: null

Sentry's Distribution option.

var environmentType: String?Default: null

Sentry's Environment option.

var releaseType: String?Default: null

Sentry's Release option.

var serverNameType: String?Default: null

Sentry's Server Name option.

Developing Extensions

If you're developing an extension for others to use, we strongly recommend [writing a plugin]. If you'd rather not do that, you should write an extension function to configure your extension:

fun ExtensionsBuilder.extMyExtension(/* args */) {
    // ...any extra configuration...

    add(::MyExtension)
}

Using ExtensionsBuilder as the receiver means users can configure your extension directly in the extensions { } builder:

ExtensibleBot(TOKEN) {
    extensions {
        extMyExtension {
            // ...
        }
    }
}