Quickstart

Build your first Discord bot with DisGo in minutes

Quickstart

This guide will walk you through creating a simple ping-pong bot that responds to messages. You’ll learn the basics of creating a DisGo client, listening for events, and interacting with Discord.

Before starting, make sure you’ve installed DisGo and have a bot token from the Discord Developer Portal.

Create your first bot

Let’s build a bot that responds to “ping” with “pong” and vice versa. This example demonstrates the core concepts of DisGo: client initialization, Gateway connections, and event handling.

1. Create the main file

   Create a new file called main.go in your project directory:

   main.go

   package main
   
   import (
       "context"
       "log/slog"
       "os"
       "os/signal"
       "syscall"
   
       "github.com/disgoorg/disgo"
       "github.com/disgoorg/disgo/bot"
       "github.com/disgoorg/disgo/discord"
       "github.com/disgoorg/disgo/events"
       "github.com/disgoorg/disgo/gateway"
   )
   
   func main() {
       slog.Info("starting example...")
       slog.Info("disgo version", slog.String("version", disgo.Version))
   
       client, err := disgo.New(os.Getenv("disgo_token"),
           bot.WithGatewayConfigOpts(
               gateway.WithIntents(
                   gateway.IntentGuildMessages,
                   gateway.IntentMessageContent,
               ),
           ),
           bot.WithEventListenerFunc(onMessageCreate),
       )
       if err != nil {
           slog.Error("error while building disgo", slog.Any("err", err))
           return
       }
   
       defer client.Close(context.TODO())
   
       if err = client.OpenGateway(context.TODO()); err != nil {
           slog.Error("errors while connecting to gateway", slog.Any("err", err))
           return
       }
   
       slog.Info("example is now running. Press CTRL-C to exit.")
       s := make(chan os.Signal, 1)
       signal.Notify(s, syscall.SIGINT, syscall.SIGTERM, os.Interrupt)
       <-s
   }
   
   func onMessageCreate(event *events.MessageCreate) {
       if event.Message.Author.Bot {
           return
       }
       var message string
       if event.Message.Content == "ping" {
           message = "pong"
       } else if event.Message.Content == "pong" {
           message = "ping"
       }
       if message != "" {
           _, _ = event.Client().Rest.CreateMessage(event.ChannelID, discord.NewMessageCreateBuilder().SetContent(message).Build())
       }
   }
   

   This example uses the disgo_token environment variable for the bot token. You can name it anything you prefer.

2. Set your bot token

   Set the environment variable with your bot token:

   export disgo_token="your_bot_token_here"
   

   Or create a .env file and load it with a package like godotenv.

   Never hardcode your token in the source code or commit it to version control!

3. Run your bot

   Start your bot with:

   go run main.go
   

   You should see output like:

   INFO starting example...
   INFO disgo version version=v0.18.0
   INFO example is now running. Press CTRL-C to exit.
   
4. Test your bot

   In Discord, send a message saying “ping” in a channel where your bot has access. The bot should respond with “pong”!

   If you send “pong”, it will respond with “ping”.

Understanding the code

Let’s break down the key components of this bot:

Client initialization

client, err := disgo.New(os.Getenv("disgo_token"),
    bot.WithGatewayConfigOpts(
        gateway.WithIntents(
            gateway.IntentGuildMessages,
            gateway.IntentMessageContent,
        ),
    ),
    bot.WithEventListenerFunc(onMessageCreate),
)

• disgo.New() creates a new bot client with your token
• Gateway intents specify which events you want to receive:
  • IntentGuildMessages - Receive message events in guilds
  • IntentMessageContent - Access message content (privileged intent)
• Event listeners register functions to handle specific events

The Message Content Intent is a privileged intent. You must enable it in the Discord Developer Portal under your bot’s settings.

Gateway connection

if err = client.OpenGateway(context.TODO()); err != nil {
    slog.Error("errors while connecting to gateway", slog.Any("err", err))
    return
}

This establishes a WebSocket connection to Discord’s Gateway, allowing your bot to receive real-time events.

Event handling

func onMessageCreate(event *events.MessageCreate) {
    if event.Message.Author.Bot {
        return
    }
    // Handle the message
}

• The event handler receives MessageCreate events
• We ignore messages from bots to prevent loops
• Access message data through event.Message

Sending messages

_, _ = event.Client().Rest.CreateMessage(
    event.ChannelID,
    discord.NewMessageCreateBuilder().SetContent(message).Build(),
)

• Use the REST client to send messages
• NewMessageCreateBuilder() provides a fluent API for constructing messages
• Send rich messages with embeds, components, and more

Graceful shutdown

defer client.Close(context.TODO())

s := make(chan os.Signal, 1)
signal.Notify(s, syscall.SIGINT, syscall.SIGTERM, os.Interrupt)
<-s

• defer client.Close() ensures cleanup when the program exits
• Signal handling allows graceful shutdown with Ctrl+C

Alternative event handling patterns

DisGo offers multiple ways to handle events. Here are some alternatives:

Event listener interface

// Implement the EventListener interface
type MyListener struct{}

func (l *MyListener) OnEvent(event bot.Event) {
    switch e := event.(type) {
    case *events.MessageCreate:
        // Handle message
    case *events.Ready:
        // Handle ready
    }
}

// Register it
client.AddEventListeners(&MyListener{})

Adding more features

Now that you have a basic bot, you can extend it with more functionality:

Slash commands

Add modern slash commands to your bot

Message components

Create interactive buttons and select menus

Embeds

Send rich embedded messages

Voice connections

Connect to voice channels

Common intents

Depending on your bot’s functionality, you’ll need different intents:

Intent	Purpose	Privileged
IntentGuilds	Guild create/update/delete events	No
IntentGuildMembers	Member join/leave/update events	Yes
IntentGuildMessages	Message events in guilds	No
IntentGuildMessageReactions	Reaction add/remove events	No
IntentDirectMessages	Direct message events	No
IntentMessageContent	Access to message content	Yes
IntentGuildPresences	User presence updates	Yes

Privileged intents require approval from Discord for verified bots in over 100 servers. Enable them in the Developer Portal first.

Next steps

Congratulations! You’ve built your first DisGo bot. Continue learning:

Basic concepts

Deep dive into DisGo’s architecture

More examples

Explore advanced examples