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.
The bot.Client is the central structure in DisGo that manages all interactions with Discord’s API. It combines REST, Gateway, caching, and event handling into a unified interface.
Client structure
The Client struct contains all the components needed to run a Discord bot:
type Client struct {
Token string
ApplicationID snowflake.ID
Logger *slog.Logger
Rest rest.Rest
EventManager EventManager
ShardManager sharding.ShardManager
Gateway gateway.Gateway
HTTPServer httpserver.Server
VoiceManager voice.Manager
Caches cache.Caches
MemberChunkingManager MemberChunkingManager
}
Key components
REST API client for making HTTP requests to Discord
Manages event listeners and dispatches events from the gateway
Single gateway connection for small bots (mutually exclusive with ShardManager)
Manages multiple gateway connections for large bots
In-memory storage for Discord entities
Creating a client
You create a client using the disgo.New() function with configuration options:
import (
"github.com/disgoorg/disgo"
"github.com/disgoorg/disgo/bot"
"github.com/disgoorg/disgo/gateway"
)
client, err := disgo.New(token,
bot.WithDefaultGateway(),
bot.WithGatewayConfigOpts(
gateway.WithIntents(gateway.IntentGuilds, gateway.IntentGuildMessages),
),
bot.WithEventListenerFunc(messageHandler),
)
if err != nil {
log.Fatal("Failed to create client:", err)
}
Configuration options
DisGo uses a functional options pattern for configuration. Here are the most important configuration options:
Gateway configuration
Single gateway
Shard manager
For bots in fewer than 2,500 guilds:client, err := disgo.New(token,
bot.WithDefaultGateway(),
bot.WithGatewayConfigOpts(
gateway.WithIntents(
gateway.IntentGuilds,
gateway.IntentGuildMessages,
gateway.IntentMessageContent,
),
gateway.WithCompress(gateway.CompressionZstdStream),
),
)
For bots in 2,500+ guilds:client, err := disgo.New(token,
bot.WithDefaultShardManager(),
bot.WithShardManagerConfigOpts(
sharding.WithAutoScaling(true),
sharding.WithGatewayConfigOpts(
gateway.WithIntents(gateway.IntentGuilds),
),
),
)
Event listeners
client, err := disgo.New(token,
bot.WithDefaultGateway(),
// Function-based listener
bot.WithEventListenerFunc(func(e *events.MessageCreate) {
log.Println("Message:", e.Message.Content)
}),
// Adapter-based listener
bot.WithEventListeners(&events.ListenerAdapter{
OnMessageCreate: handleMessage,
OnGuildCreate: handleGuild,
}),
)
Cache configuration
import "github.com/disgoorg/disgo/cache"
client, err := disgo.New(token,
bot.WithCacheConfigOpts(
cache.WithCaches(
cache.FlagGuilds,
cache.FlagChannels,
cache.FlagMembers,
),
),
)
Logging
import "log/slog"
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
client, err := disgo.New(token,
bot.WithLogger(logger),
bot.WithDefaultGateway(),
)
Client methods
Gateway lifecycle
Open the gateway
ctx := context.Background()
if err := client.OpenGateway(ctx); err != nil {
log.Fatal("Failed to connect:", err)
}
Handle events
Events are dispatched to your configured listeners automatically.
Close the client
defer client.Close(context.Background())
Event management
// Add listeners dynamically
client.AddEventListeners(
bot.NewListenerFunc(func(e *events.MessageCreate) {
// Handle message
}),
)
// Remove listeners
client.RemoveEventListeners(listener)
Presence updates
import "github.com/disgoorg/disgo/discord"
err := client.SetPresence(ctx,
gateway.WithPresenceActivities(
discord.Activity{
Name: "with the Discord API",
Type: discord.ActivityTypeGame,
},
),
gateway.WithPresenceStatus(discord.OnlineStatusDND),
)
Member chunking
// Request all members for a guild
err := client.RequestMembersWithQuery(ctx,
guildID,
true, // include presences
"", // nonce
"", // query (empty = all)
0, // limit (0 = all)
)
Checking client state
// Check if gateway is configured
if client.HasGateway() {
log.Println("Single gateway mode")
}
// Check if shard manager is configured
if client.HasShardManager() {
log.Println("Sharded mode")
}
// Get bot user ID
botID := client.ID()
// Get current gateway/shard for a guild
shard, err := client.Shard(guildID)
Complete example
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/disgoorg/disgo"
"github.com/disgoorg/disgo/bot"
"github.com/disgoorg/disgo/events"
"github.com/disgoorg/disgo/gateway"
)
func main() {
// Create client
client, err := disgo.New(os.Getenv("TOKEN"),
bot.WithDefaultGateway(),
bot.WithGatewayConfigOpts(
gateway.WithIntents(
gateway.IntentGuilds,
gateway.IntentGuildMessages,
gateway.IntentMessageContent,
),
),
bot.WithEventListeners(&events.ListenerAdapter{
OnMessageCreate: func(e *events.MessageCreate) {
if e.Message.Content == "ping" {
_, _ = e.Client().Rest.CreateMessage(
e.ChannelID,
discord.MessageCreate{Content: "pong"},
)
}
},
}),
)
if err != nil {
log.Fatal(err)
}
// Ensure cleanup
defer client.Close(context.Background())
// Connect to Discord
if err = client.OpenGateway(context.Background()); err != nil {
log.Fatal(err)
}
// Wait for interrupt
s := make(chan os.Signal, 1)
signal.Notify(s, syscall.SIGINT, syscall.SIGTERM)
<-s
}
The client automatically handles reconnection, rate limiting, and session resumption when the gateway connection is lost.
Always call client.Close() before your application exits to gracefully disconnect from Discord and clean up resources.