Skip to main content
The Client interface is the core component of DisGoLink, managing Lavalink nodes, players, and event listeners.

​
Creating a Client

Create a new client with disgolink.New(): 
import (
    "github.com/disgoorg/disgolink/v3"
    "github.com/disgoorg/snowflake/v2"
)

client := disgolink.New(userID)
​
userID
snowflake.ID
required
The Discord bot’s user ID

​
Configuration Options

Customize the client with ConfigOpt functions: 
client := disgolink.New(userID,
    disgolink.WithLogger(customLogger),
    disgolink.WithHTTPClient(httpClient),
    disgolink.WithListeners(listener1, listener2),
    disgolink.WithPlugins(plugin1, plugin2),
)

​
Available Options

​
WithLogger
func(*slog.Logger) ConfigOpt
Inject a custom structured logger
​
WithHTTPClient
func(*http.Client) ConfigOpt
Provide a custom HTTP client for REST requests (default timeout: 10s)
​
WithListeners
func(...EventListener) ConfigOpt
Register event listeners at initialization
​
WithListenerFunc
func[E lavalink.Message](func(Player, E)) ConfigOpt
Register a typed event listener function
​
WithPlugins
func(...Plugin) ConfigOpt
Add plugins to extend functionality

​
Node Management

​
Adding Nodes

Connect to a Lavalink server: 
node, err := client.AddNode(ctx, disgolink.NodeConfig{
    Name:      "main-node",
    Address:   "localhost:2333",
    Password:  "youshallnotpass",
    Secure:    false,
    SessionID: "", // Optional: for session resuming
})
​
AddNode
func(context.Context, NodeConfig) (Node, error)
Adds and connects to a new Lavalink node. Returns immediately after establishing connection.

​
Retrieving Nodes

​
Node
func(name string) Node
Get a specific node by name
​
BestNode
func() Node
Automatically select the node with the best performance based on CPU, memory, and system load statistics
​
ForNodes
func(func(Node))
Iterate over all registered nodes
​
RemoveNode
func(name string)
Disconnect and remove a node by name
// Get specific node
node := client.Node("main-node")

// Get best available node
bestNode := client.BestNode()

// Iterate all nodes
client.ForNodes(func(node disgolink.Node) {
    fmt.Println(node.Config().Name, node.Status())
})

​
Player Management

​
Creating Players

​
Player
func(snowflake.ID) Player
Get or create a player for a guild using the best available node
​
PlayerOnNode
func(Node, snowflake.ID) Player
Get or create a player on a specific node
​
ExistingPlayer
func(snowflake.ID) Player
Get an existing player without creating a new one (returns nil if not found)
// Create/get player on best node
player := client.Player(guildID)

// Create/get player on specific node
player := client.PlayerOnNode(node, guildID)

// Check if player exists
if player := client.ExistingPlayer(guildID); player != nil {
    // Player exists
}

​
Managing Players

​
ForPlayers
func(func(Player))
Iterate over all active players
​
RemovePlayer
func(snowflake.ID)
Remove a player from the client’s cache (does not destroy the player on the node)
// Iterate all players
client.ForPlayers(func(player disgolink.Player) {
    fmt.Printf("Guild: %d, Track: %v\n", player.GuildID(), player.Track())
})

​
Event System

​
Adding Listeners

​
AddListeners
func(...EventListener)
Register one or more event listeners
​
RemoveListeners
func(...EventListener)
Unregister event listeners
​
EmitEvent
func(Player, lavalink.Message)
Manually emit an event to all registered listeners (typically used internally)
// Add listener
client.AddListeners(myListener)

// Add typed listener function
client.AddListeners(disgolink.NewListenerFunc(func(p disgolink.Player, e lavalink.TrackStartEvent) {
    fmt.Printf("Track started: %s\n", e.Track.Info.Title)
}))
See the Events page for details on implementing listeners.

​
Voice State Updates

Forward Discord voice events to the client:
​
OnVoiceServerUpdate
func(context.Context, snowflake.ID, string, string)
Handle Discord VOICE_SERVER_UPDATE eventsParameters:
  • ctx: Context
  • guildID: Guild snowflake ID
  • token: Voice connection token
  • endpoint: Voice server endpoint
​
OnVoiceStateUpdate
func(context.Context, snowflake.ID, *snowflake.ID, string)
Handle Discord VOICE_STATE_UPDATE eventsParameters:
  • ctx: Context
  • guildID: Guild snowflake ID
  • channelID: Voice channel ID (nil if disconnected)
  • sessionID: Voice session ID
// In your Discord event handler
func handleVoiceServerUpdate(event *gateway.EventVoiceServerUpdate) {
    client.OnVoiceServerUpdate(context.Background(), event.GuildID, event.Token, event.Endpoint)
}

func handleVoiceStateUpdate(event *gateway.EventVoiceStateUpdate) {
    if event.UserID != botUserID {
        return
    }
    client.OnVoiceStateUpdate(context.Background(), event.GuildID, event.ChannelID, event.SessionID)
}
Both voice events must be forwarded to DisGoLink for proper voice connection establishment.

​
Additional Methods

​
UserID
func() snowflake.ID
Get the bot’s user ID
​
Close
func()
Close all node connections and shut down the client
// Get user ID
userID := client.UserID()

// Shutdown
defer client.Close()

​
Plugin System

Extend client functionality with plugins:
​
AddPlugins
func(...Plugin)
Register plugins
​
ForPlugins
func(func(Plugin))
Iterate over registered plugins
​
RemovePlugins
func(...Plugin)
Unregister plugins
client.AddPlugins(myPlugin)
Plugins can implement various interfaces like PluginEventHandler, EventPlugin, and OpPlugin to hook into different lifecycle events.

Build docs developers (and LLMs) love

Get started for freeTalk to us