Client

Understanding the bot.Client structure and how to build and configure your Discord bot

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:

bot/client.go

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 · rest.Rest

REST API client for making HTTP requests to Discord

EventManager · EventManager

Manages event listeners and dispatches events from the gateway

Gateway · gateway.Gateway

Single gateway connection for small bots (mutually exclusive with ShardManager)

ShardManager · sharding.ShardManager

Manages multiple gateway connections for large bots

Caches · cache.Caches

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

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),
    ),
)

Shard manager

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

1. Open the gateway

   ctx := context.Background()
   if err := client.OpenGateway(ctx); err != nil {
       log.Fatal("Failed to connect:", err)
   }
   
2. Handle events

   Events are dispatched to your configured listeners automatically.

3. 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.