Getting Started

Creating a bot application

1. Go to https://discord.com/developers/applications

2. Click 'New Application'
   

3. Much like a user, your bot will need a username, click 'Create' when you're done
   

4. You'll be brought to your application's page. Next, we'll turn our application into a bot. For this, you have to click 'Bot' in the sidebar menu on the left.
   

5. Click 'Add bot', read the warning and accept.
   

Congrats, you now have a bot! A whole bunch of toggle buttons and checkboxes have appeared. Read each one, if you don't understand what they mean it's best to leave them on their default state.

6. If you want your bot to be able to read the content of messages (like "!ping" in the example below) you have to enable the 'Message Content Intent' toggle.
   

7. Next up, we'll have our bot join one of our servers. Go to the 'OAuth2' > 'URL Generator' tab
   

8. Toggle the 'bot' scope, choose the permissions for your bot and 'copy' the url that appeared at the bottom of the page.
   

9. Paste the url in your browser and select a server for your bot
   

That's it! You have created a bot and put it in your discord server.

Starting your bot with Kord

Go to your bot's application page from the previous section of this guide. There's a Token section with a 'Copy' button. This'll put your bot's token in your clipboard.

Note:

Never ever ever ever ever, share this code with anyone. Don't put it on github, don't put it in Discord. This is the equivalent of your bot's password. People can do very bad things with it.

Right now we assume you have basic knowledge of gradle or maven, you can find out how to add Kord to your project in the installation section of the README.

The minimal code to get your bot online is the following:

suspend fun main() {
    val kord = Kord("your bot token")

    kord.login()
}

Run this code, and your bot will appear online in your client's sidebar. login Will keep your bot logged in until you tell it to log out, or stop the program through some other means.

Making a simple ping-pong bot

Copy the code above:

suspend fun main() {
    val kord = Kord("your bot token")

    kord.login()
}

Kord allows you to listen to events either through the events property, or the on extension function.

Since our requirements are pretty simple, we'll use the latter. We'll want to listen to a newly created message, aka MessageCreateEvent:

suspend fun main() {
    val kord = Kord("your bot token")

    kord.on<MessageCreateEvent> { // runs every time a message is created that our bot can read

        // ignore other bots, even ourselves. We only serve humans here!
        if (message.author?.isBot != false) return@on

        // check if our command is being invoked
        if (message.content != "!ping") return@on

        // all clear, give them the pong!
        message.channel.createMessage("pong!")
    }

    kord.login {
        // we need to specify this to receive the content of messages
        @OptIn(PrivilegedIntent::class)
        intents += Intent.MessageContent
    }
}

That's it, you now have a bot that'll respond pongs to your pings. With that, you have the very basics covered.

Note:

login will supend until the bot logs out, this stops the program from reaching the end of the main function and ending. It also means that whatever code you write after login will only run after your bot was logged out. If you follow this pattern, you should add your event listeners before calling login.