Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/disgoorg/disgo/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
// 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:
IntentPurposePrivileged
IntentGuildsGuild create/update/delete eventsNo
IntentGuildMembersMember join/leave/update eventsYes
IntentGuildMessagesMessage events in guildsNo
IntentGuildMessageReactionsReaction add/remove eventsNo
IntentDirectMessagesDirect message eventsNo
IntentMessageContentAccess to message contentYes
IntentGuildPresencesUser presence updatesYes
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

Build docs developers (and LLMs) love

Get started for freeTalk to us