Skip to main content
This guide covers how to set up and connect your DisGoLink client to a Lavalink server.

​
Prerequisites

Before connecting to Lavalink, ensure you have:
  • A running Lavalink server instance
  • The server’s connection details (address, password)
  • Your Discord bot’s application ID
1

Initialize the client

First, create a DisGoLink client with your bot’s application ID:
import (
    "github.com/disgoorg/disgolink/v3/disgolink"
    "github.com/disgoorg/snowflake/v2"
)

// Create the DisGoLink client
lavalinkClient := disgolink.New(applicationID)
You can also configure the client with optional settings:
lavalinkClient := disgolink.New(
    applicationID,
    disgolink.WithLogger(customLogger),
    disgolink.WithHTTPClient(customHTTPClient),
    disgolink.WithListeners(eventListener),
)
2

Configure the node

Set up your node configuration with the connection details:
nodeConfig := disgolink.NodeConfig{
    Name:      "main-node",              // Friendly name for this node
    Address:   "localhost:2333",         // Lavalink server address
    Password:  "youshallnotpass",        // Server password
    Secure:    false,                    // Use WSS/HTTPS (set true for production)
    SessionID: "",                       // Leave empty for new connections
}
NodeConfig Fields:
  • Name: A unique identifier for this node
  • Address: The host and port of your Lavalink server
  • Password: Authentication password (configured in Lavalink’s application.yml)
  • Secure: Set to true to use WSS/HTTPS instead of WS/HTTP
  • SessionID: For resuming existing sessions (leave empty initially)
3

Add the node

Connect to the Lavalink server by adding the node:
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

node, err := lavalinkClient.AddNode(ctx, nodeConfig)
if err != nil {
    log.Fatalf("Failed to add node: %v", err)
}
The AddNode() method:
  • Establishes a WebSocket connection to Lavalink
  • Authenticates using the provided password
  • Returns a Node interface for interacting with the server
4

Verify the connection

Confirm the connection is successful:
// Get the Lavalink version
version, err := node.Version(ctx)
if err != nil {
    log.Fatalf("Failed to get version: %v", err)
}
log.Printf("Connected to Lavalink %s", version)

// Get the session ID
sessionID := node.SessionID()
log.Printf("Session ID: %s", sessionID)

// Check node status
status := node.Status()
log.Printf("Node status: %s", status) // CONNECTED

​
Connection Status

DisGoLink tracks the connection state through the Status type:
StatusDescription
CONNECTINGInitial connection attempt in progress
CONNECTEDSuccessfully connected to Lavalink
RECONNECTINGAttempting to reconnect after disconnection
DISCONNECTEDNot connected to the server
Check the current status: 
if node.Status() == disgolink.StatusConnected {
    log.Println("Node is ready!")
}

​
Session Resuming

DisGoLink supports session resuming to maintain player state across reconnections. 
// Update session to enable resuming
err := node.Update(ctx, lavalink.SessionUpdate{
    Resuming:  json.Ptr(true),
    Timeout:   json.Ptr(60), // Resume timeout in seconds
})

​
Automatic Reconnection

DisGoLink automatically handles reconnection when the connection is lost:
  • Exponential Backoff: Increases delay between reconnection attempts (up to 30 seconds)
  • Infinite Retries: Continues attempting to reconnect indefinitely
  • State Preservation: Maintains player state when session resuming is enabled
// Monitor connection status through logs
logger := slog.Default()
lavalinkClient := disgolink.New(
    applicationID,
    disgolink.WithLogger(logger),
)
The client will log reconnection attempts automatically: 
INFO  opening connection to node...
ERROR failed to reconnect node try=0
INFO  successfully resumed session session_id=abc123

​
Managing Multiple Nodes

You can connect to multiple Lavalink servers for load balancing: 
// Add multiple nodes
node1, _ := lavalinkClient.AddNode(ctx, disgolink.NodeConfig{
    Name:     "node-1",
    Address:  "lava1.example.com:2333",
    Password: "password1",
})

node2, _ := lavalinkClient.AddNode(ctx, disgolink.NodeConfig{
    Name:     "node-2",
    Address:  "lava2.example.com:2333",
    Password: "password2",
})

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

// Get a specific node by name
node := lavalinkClient.Node("node-1")

// Iterate over all nodes
lavalinkClient.ForNodes(func(node disgolink.Node) {
    log.Printf("Node: %s - Status: %s", node.Config().Name, node.Status())
})

​
Cleanup

Always close the client when shutting down: 
defer lavalinkClient.Close()
This will:
  • Close all node connections gracefully
  • Stop all active players
  • Release associated resources

​
Next Steps

Loading Tracks

Learn how to search and load tracks from various sources

Playing Audio

Start playing audio in Discord voice channels

Build docs developers (and LLMs) love

Get started for freeTalk to us