Bot package

High-level Discord bot client for interacting with Discord’s API

The bot package provides a high-level client for interacting with Discord’s API. It combines the functionality of REST, Gateway/Sharding, HTTP Server, and Cache into one easy-to-use package.

Client

The Client struct is the main entry point for building Discord bots with DisGo.

Type definition

type Client struct {
    Token                 string
    ApplicationID         snowflake.ID
    Logger                *slog.Logger
    Rest                  rest.Rest
    EventManager          EventManager
    Gateway               gateway.Gateway
    ShardManager          sharding.ShardManager
    HTTPServer            httpserver.Server
    VoiceManager          voice.Manager
    Caches                cache.Caches
    MemberChunkingManager MemberChunkingManager
}

Token · string

The bot token used for authentication

ApplicationID · snowflake.ID

The application ID of the bot

Rest · rest.Rest

REST client for making HTTP requests to Discord’s API

EventManager · EventManager

Manages event listeners and dispatches events

Gateway · gateway.Gateway

WebSocket connection to Discord’s Gateway (for single shard)

ShardManager · sharding.ShardManager

Manages multiple shards for large bots

Methods

OpenGateway

func (c *Client) OpenGateway(ctx context.Context) error

Opens a connection to the Discord Gateway. Returns an error if no gateway is configured or if the connection fails.

OpenShardManager

func (c *Client) OpenShardManager(ctx context.Context) error

Opens all shard connections managed by the ShardManager. Returns an error if no shard manager is configured.

Close

func (c *Client) Close(ctx context.Context)

Closes all connections (voice, gateway, rest, shard manager, HTTP server) gracefully. Waits for the context to be done or all resources to close.

ID

func (c *Client) ID() snowflake.ID

Returns the bot’s user ID from the cache. Returns 0 if the self user is not cached yet.

AddEventListeners

func (c *Client) AddEventListeners(listeners ...EventListener)

Adds one or more event listeners to the client’s event manager.

RemoveEventListeners

func (c *Client) RemoveEventListeners(listeners ...EventListener)

Removes one or more event listeners from the client’s event manager.

UpdateVoiceState

func (c *Client) UpdateVoiceState(ctx context.Context, guildID snowflake.ID, channelID *snowflake.ID, selfMute bool, selfDeaf bool) error

Updates the bot’s voice state in a guild. Used to join/leave voice channels.

guildID · snowflake.ID

The guild ID to update voice state in

channelID · *snowflake.ID

The channel ID to join, or nil to disconnect from voice

selfMute · bool

Whether the bot should be muted

selfDeaf · bool

Whether the bot should be deafened

SetPresence

func (c *Client) SetPresence(ctx context.Context, opts ...gateway.PresenceOpt) error

Sets the bot’s presence (status and activities). Only works with a single gateway connection.

Configuration

The bot client is configured using functional options.

ConfigOpt

type ConfigOpt func(config *config)

A function type used to configure the bot client.

Common configuration options

WithLogger

func WithLogger(logger *slog.Logger) ConfigOpt

Sets a custom logger for the bot.

WithDefaultGateway

func WithDefaultGateway() ConfigOpt

Creates a gateway connection with sensible defaults.

WithGatewayConfigOpts

func WithGatewayConfigOpts(opts ...gateway.ConfigOpt) ConfigOpt

Configures the default gateway with additional options.

WithDefaultShardManager

func WithDefaultShardManager() ConfigOpt

Creates a shard manager with sensible defaults for large bots.

WithEventListeners

func WithEventListeners(eventListeners ...EventListener) ConfigOpt

Adds event listeners during bot initialization.

WithEventListenerFunc

func WithEventListenerFunc[E Event](f func(e E)) ConfigOpt

Adds a type-safe event listener function using generics.

WithCacheConfigOpts

func WithCacheConfigOpts(opts ...cache.ConfigOpt) ConfigOpt

Configures the default cache settings.

Event system

EventManager

type EventManager interface {
    AddEventListeners(eventListeners ...EventListener)
    RemoveEventListeners(eventListeners ...EventListener)
    HandleGatewayEvent(gateway gateway.Gateway, eventType gateway.EventType, sequenceNumber int, event gateway.EventData)
    HandleHTTPEvent(respondFunc httpserver.RespondFunc, event httpserver.EventInteractionCreate)
    DispatchEvent(event Event)
}

The EventManager handles routing events from the gateway to registered listeners.

EventListener

type EventListener interface {
    OnEvent(event Event)
}

Interface that event listeners must implement.

Event

type Event interface {
    Client() *Client
    SequenceNumber() int
}

Base interface for all events.

Creating event listeners

NewListenerFunc

func NewListenerFunc[E Event](f func(e E)) EventListener

Creates a type-safe event listener from a function. The listener will only receive events of type E.

Example:

messageListener := bot.NewListenerFunc(func(e *events.MessageCreate) {
    fmt.Println("Message received:", e.Message.Content)
})

NewListenerChan

func NewListenerChan[E Event](c chan<- E) EventListener

Creates an event listener that sends events to a channel.

Example:

messageChan := make(chan *events.MessageCreate)
messageListener := bot.NewListenerChan(messageChan)