Bundled Converters

Kord Extensions includes many built-in converters. They cover the most common use-cases (and some uncommon ones), but you can always make your own if needed.

General

Boolean Converter

Name:booleanTypes:

defaulting

list

optional

single

Value:Boolean

Boolean converter, with support for translated values.

Supported Values

This converter supports the following values, specified below in English. You can also use names in your own language, provided Kord Extensions has translations for it.

• True: 1, y, yes, t, true
• False: 0, n, no, f false

Colour Converter

Names:colorcolourTypes:

defaulting

list

optional

single

Value:dev.kord.common.Color

Colour converter, supporting hex codes prefixed with # or 0x, plain RGB integers, or colour names matching Discord's historical branding colours.

This converter returns Kord Color objects.

Discord Colours

This converter supports the following values, specified below in English. You can also use names in your own language, provided Kord Extensions has translations for it.

• Black: black, blck, blk
• Blurple: blurple, purple, purp, prpl, prp
• Fuchsia: fuchsia, pink, pnk
• Green: green, grn
• Light Blurple: light blurple, lblurple, light blurp, lblurp, light purple, lpurple, light purp, lpurp, light prpl, lprpl, light prp, lprp
• Red: red, rd
• White: white, wht
• Yellow: yellow, ylw

Decimal Converter

Name:decimalTypes:

defaulting

list

optional

single

Value:Double

Decimal converter, parsing the provided value into a Double.

This converter supports some extra settings:

var maxValueType: Double?Default: null

The maximum allowed input value.

var minValueType: Double?Default: null

The minimum allowed input value.

Duration Converter

Name:durationTypes:

coalescing

defaulting

optional

single

Value:kotlinx.datetime.DateTimePeriod

Duration converter, using a complex parsing strategy to parse arguments into DateTimePeriod objects. These objects are timezone-agnostic, and you may need to normalise them against a specific timezone.

If you're writing a chat command, consider using the coalescing variant for this converter, allowing users to supply spaces in their input.

This converter supports some extra settings:

var longHelpType: BooleanDefault: true

Whether to respond with a long help message on parsing failures, explaining exactly how to specify durations and what time units are supported.

Set this to false if you only want to tell the user that they provided an invalid time unit.

var positiveOnlyType: BooleanDefault: true

Whether the converter should only accept a positive duration.

Set this to false if you also want to accept negative durations.

Along with Discord-formatted timestamps, this converter supports specifying durations as a series of units and numbers.

Parsing Specification

Users can specify durations as pairs containing both a unit and a numeric value, including prefixing numbers with a minus sign (-) to make them negative.. The parser removes commas, spaces, and the plus character (+) before parsing.

Pairs work when specified in any order, and duplicates are added/subtracted. The parser supports both ordered forms to allow for natural input in right-to-left languages:

• Value first: 12 days
• Unit first: d12

Users can prefix numbers with a minus sign (-) to make them negative. The parser only supports base-10 ASCII integers.

Supported Units

The parser supports the following units, which are listed below with their English names. You can also use names in your own language, provided Kord Extensions has translations for it.

• Seconds: s, sec, secs, second, seconds
• Minutes: m, mi, min, mins, minute, minutes
• Hours: h, hr, hour, hours
• Days: d, day, days
• Weeks: w, wk, week, weeks
• Months: mo, mth, month, months
• Years: y, yr, year, years

Examples

The following examples are valid duration strings:

• 12d 4h 30m - 12 days, 4 hours and 30 minutes.
• 12d 4h 30m -1 w - 5 days (12 - 7), 4 hours and 30 minutes.
• -2d 1w 6h -2h - 5 days (7 - 2) and 4 hours (6 - 2).
• 周3 日2 分30 - in Simplified Chinese, 23 days (3 * 7 + 2) and 30 minutes.

The following examples are invalid:

• 12 - bare numbers are not supported, a unit is required.
• 12m d w - all units require a numerical value.
• -5 days with positiveOnly = true - the current converter only accepts positive durations.

Email Converter

Name:emailTypes:

defaulting

list

optional

single

Value:String

Email converter, validating that the provided input is a well-formatted email address, according to Apache Commons' email validator.

Enumeration Converter

Name:enumTypes: Value:ChoiceEnum<T>

Arbitrary enum converter, converting arguments based on a defined getter.

Your enum must extend ChoiceEnum and implement the readableName property, which is a translation key representing a human-readable name to show on Discord for each enum entry.

This converter has some required extra settings:

var typeNameType: Key

Translation key representing a short (one or two word) lower-case name for whatever the enum represents to the user.

For example, if your enum is named IssueStatuses and contains open, closed and invalid entries, your translation key should, in English, resolve to status or issue status.

It also supports some extra settings:

var getterType: suspend (String, Locale) -> E?Default: ::getEnum

Getter used to resolve the correct enum entry. The default strategy (named getEnum) searches through the possible enum entries, returning the first one that matches one of the following, case-insensitively:

• The translated string referred to by readableName.
• The string translation key referred to by readableName.
• The literal name of the enum entry as written in code.

Integer Converter

Name:intTypes:

defaulting

list

optional

single

Value:Int

Integer converter, parsing the provided value into an Int.

This converter supports some extra settings:

var maxValueType: Double?Default: null

The maximum allowed input value.

var minValueType: Double?Default: null

The minimum allowed input value.

var radix Type: IntDefault: 10

The radix (base) used when parsing.

Long Converter

Name:longTypes:

defaulting

list

optional

single

Value:Long

Long converter, parsing the provided value into a Long.

This converter supports some extra settings:

var maxValueType: Int?Default: null

The maximum allowed input value.

var minValueType: Int?Default: null

The minimum allowed input value.

var radix Type: IntDefault: 10

The radix (base) used when parsing.

String Converter

Name:stringTypes:

coalescing

defaulting

list

optional

single

Value:String

String converter, returning the argument's value verbatim.

This converter supports some extra settings:

var maxLength Type: Int?Default: null

The maximum allowable input length.

var minLength Type: Int?Default: null

The minimum allowable input length.

Supported Locale Converter

Name:supportedLocaleTypes:

defaulting

list

optional

single

Value:Locale

Supported locale converter, converting arguments into Locale objects representing the locales Kord Extensions supports.

Supported locales are defined here. If a locale you need isn't supported, please feel free to contribute translations for it.

Discord Entities

Channel Converter

Name:channelTypes:

list

optional

single

Value:dev.kord.core.entity.channel.Channel

Discord channel converter, converting the input to a resolved Kord Channel object. This converter behaves differently depending on command type:

• Chat commands: Supports mentions, IDs, names, and this to refer to the current channel.
• Slash commands: Uses the resolved object Discord provides, and can't do its own parsing or resolution.

This converter supports some extra settings:

requireChannelType(...)

Add a channel type to the set of acceptable types.

By default, this converter doesn't limit the acceptable channel types. Providing at least one turns on this requirement.

Arguments

typeType: ChannelType

var requiredChannelTypesType: MutableSet<ChannelType>Default: mutableSetOf()

The set of acceptable channel types, usually mutated by requireChannelType(type), but you can set it yourself if you prefer.

By default, this converter doesn't limit the acceptable channel types. Providing at least one turns on this requirement.

var requiredGuildType: (suspend () -> Snowflake)?Default: null

For chat commands: Callback that returns a Snowflake representing a predefined guild the supplied channel must exist on.

Channels passed to slash commands are already limited to the same guild the command was executed on, so this setting does nothing in that case.

var requireSameGuildType: BooleanDefault: true

For chat commands: Whether the provided channel must exist on the same guild used to execute the command. If the command was executed in DMs, the argument will always be considered invalid.

Channels passed to slash commands are already limited to the same guild the command was executed on, so this setting does nothing in that case.

Emoji Converter

Name:emojiIntent:

GuildEmojis

Types:

list

optional

single

Value:dev.kord.core.entity.Emoji

Emoji converter, parsing the input into a Kord Emoji object.

Note: Your bot must have the GuildEmojis intent for custom/guild emojis.

This converter supports the following input styles:

• Unicode emojis.
• Discord custom/guild emojis.
• Custom/guild emoji IDs, with or without surrounding colons (:).
• Custom/guild emoji names, with or without surrounding colons (:), resolved using the first matching emoji your bot can find on any of its guilds.
• Unicode emoji names, as used in Discord's emoji picker.

Guild Converter

Name:guildTypes:

list

optional

single

Value:dev.kord.core.entity.Guild

Discord guild converter, converting the input to a resolved Kord Guild object. This converter supports IDs, names, and this to refer to the current guild.

Member Converter

Name:memberTypes:

list

optional

single

Value:dev.kord.core.entity.Member

Discord member converter, converting the input to a resolved Kord Guild Member object. This converter behaves differently depending on command type:

• Chat commands: Supports mentions, IDs, names, you to refer to the bot, and me to refer to the user executing the command.
• Slash commands: Uses the resolved object Discord provides, and can't do its own parsing or resolution.

This converter supports some extra settings:

var requiredGuildType: (suspend () -> Snowflake)?Default: null

Callback that returns a Snowflake representing a predefined guild the supplied member must exist on. This will also limit command executions to that guild.

var requireSameGuildType: BooleanDefault: true

Whether the provided member must exist on the same guild used to execute the command. If the command was executed in DMs, the argument will always be considered invalid.

var useReplyType: BooleanDefault: true

For chat commands: Whether to use the author of the replied-to message, when there is one. If the command was executed in DMs, the argument will always be considered invalid.

Message Converter

Name:messageTypes:

list

optional

single

Value:dev.kord.core.entity.Message

Discord message converter, converting the input to a resolved Kord Message object. This converter supports jump URLs and IDs, and the converter assumes that provided IDs refer to messages in the current channel.

Messages will be retrieved if they're not already in Kord's cache, which requires the bot to be able to see the message in question. Your bot cannot resolve jump URLs referring to messages in DMs.

This converter supports some extra settings:

var requiredGuildType: (suspend () -> Snowflake)?Default: null

Callback that returns a Snowflake representing a predefined guild the supplied message must exist on. This will also limit command executions to that guild.

var requireSameGuildType: BooleanDefault: true

When requiredGuild is specified, whether the message must exist on guild returned by that callback. Otherwise, whether the provided message must exist on the same guild used to execute the command.

If the command was executed in DMs and this setting is true, the argument will always be considered invalid.

var useReplyType: BooleanDefault: true

Whether to use the author of the replied-to message, when there is one.

Role Converter

Name:roleTypes:

list

optional

single

Value:dev.kord.core.entity.Role

Discord role converter, converting the input to a resolved Kord Role object.

This converter doesn't support resolving roles via commands run in DMs. It also behaves differently depending on command type:

• Chat commands: Supports mentions, IDs and names.
• Slash commands: Uses the resolved object Discord provides, and can't do its own parsing or resolution.

This converter supports some extra settings:

var requiredGuildType: (suspend () -> Snowflake)?Default: null

For chat commands: Callback that returns a Snowflake representing a predefined guild the supplied role must exist on.

Roles passed to slash commands are already limited to the same guild the command was executed on, so this setting does nothing in that case.

Snowflake Converter

Name:snowflakeTypes:

defaulting

list

optional

single

Value:dev.kord.common.entity.Snowflake

Discord snowflake converter, converting the input to a Kord Snowflake object.

Tag Converter

Name:tagTypes:

list

optional

single

Value:dev.kord.common.entity.ForumTag

Discord tag converter, converting the input to a resolved Kord ForumTag object.

This converter supports tag names, supplied via the built-in auto-completion based on its settings:

• Default: Use the parent channel for the current forum thread, if the command is being run within one.
• With Channel Getter: Always use the forum channel returned by the getter.

If you don't provide a channel getter and a user runs this command outside of a forum thread, your bot won't be able to resolve any tags.

var channelGetter Type: (suspend () -> ForumChannel?)?Default: null

Callback that returns a ForumChannel representing a predefined forum channel the supplied tag must exist on.

Timestamp Converter

Name:timestampTypes:

defaulting

list

optional

single

Value:dev.kordex.core.commands.converters.impl.FormattedTimestamp

Discord-formatted timestamp converter, converting the input to a FormattedTimestamp object, which includes the corresponding Instant and TimestampType.

This converter only supports Discord-formatted timestamps. For duration parsing (which includes Discord-formatted timestamps), see the Duration converter above.

User Converter

Name:userTypes:

list

optional

single

Value:dev.kord.core.entity.User

Discord user converter, converting the input to a resolved Kord User object. This converter behaves differently depending on command type:

• Chat commands: Supports mentions, IDs, usernames, tags, you to refer to the bot, and me to refer to the user executing the command.
• Slash commands: Uses the resolved object Discord provides, and can't do its own parsing or resolution.

This converter supports some extra settings:

var useReplyType: BooleanDefault: true

For chat commands: Whether to use the author of the replied-to message, when there is one.

Slash Commands

Attachment Converter

Name:attachmentTypes:

optional

single

Value:dev.kord.core.entity.Attachment

Discord attachment converter, supplied as a file when invoking a slash command. Discord provides a drop target for this type of argument.

This converter doesn't support chat commands.

Unsafe

These converters are dangerous!

We included these converters because they are useful in limited situations, but they can be dangerous if not used correctly, with their access limited to trusted users.

These converters may slow down or crash your bot, or result in data exposure problems when used incorrectly. Use them at your own risk!

Regular Expression Converter

Name:regexTypes:

coalescing

defaulting

list

optional

single

Value:Regex

Regular expression converter, allowing users to supply a regular expression.

Remember that untrusted regular expressions are dangerous, and executing them carries risks (such as catastrophic backtracking) that this converter isn't designed to prevent. If you need to execute untrusted regular expressions, consider writing a custom converter using Google's RE2/J library.

This converter supports some extra settings:

var options Type: MutableSet<RegexOption>Default: setOf()

Regular expression options used to create the Regex object.

Serialized Converter

Name:serializedTypes:

defaulting

list

optional

single

Value:T

Serialized value converter, converting argument values to the given type using kotlinx.serialization.

This isn't how kotlinx.serialization is supposed to be used. This converter is a best-effort attempt to support new argument types without writing a custom converter, and it's important to thoroughly test any code using this before deploying it.

This converter has some required extra settings:

var typeNameType: Key

Translation key representing a short (one or two word) lower-case name for whatever the value type represents to the user.

For example, if your type is named IssueStatus and contains OpenStatus, ClosedStatus and InvalidStatus values, your translation key should, in English, resolve to status or issue status.