WebSocket API

Overview

The Lavalink WebSocket API provides real-time bidirectional communication for player events, stats, and state updates. All WebSocket connections are established at /v4/websocket.

Connection Setup

Opening a Connection

Establish a WebSocket connection to:

ws://your-lavalink-host:2333/v4/websocket

Required Headers

Authorization

string

required

The password configured in your Lavalink server config

User-Id

string

required

The user ID of your Discord bot

Client-Name

string

required

The name of your client in NAME/VERSION format (e.g., lavalink-client/2.0.0)

Session-Id

string

The session ID from a previous connection to resume that session

Example Connection Headers

Authorization: youshallnotpass
User-Id: 170939974227541168
Client-Name: lavalink-client/2.0.0

Message Format

All WebSocket messages follow this standard format:

string

required

The operation type identifying the message purpose

...

varies

Additional fields specific to the operation type

OP Types

Ready OP

Dispatched when you successfully connect and authenticate with the Lavalink node.

string

required

Always "ready"

resumed

boolean

required

Whether this connection resumed a previous session

sessionId

string

required

The Lavalink session ID for this connection (not a Discord voice session ID)

{
  "op": "ready",
  "resumed": false,
  "sessionId": "session123abc"
}

Player Update OP

Dispatched at regular intervals (configurable in application.yml) with the current player state.

string

required

Always "playerUpdate"

guildId

string

required

The Discord guild ID of the player

state

object

required

The current player state

Show Player State Properties

time

integer

required

Unix timestamp in milliseconds

position

integer

required

The position of the track in milliseconds

connected

boolean

required

Whether Lavalink is connected to the Discord voice gateway

ping

integer

required

The ping to the Discord voice server in milliseconds (-1 if not connected)

{
  "op": "playerUpdate",
  "guildId": "817327181659111454",
  "state": {
    "time": 1500467109,
    "position": 60000,
    "connected": true,
    "ping": 50
  }
}

Stats OP

Dispatched once per minute with server statistics.

string

required

Always "stats"

players

integer

required

The number of players connected to the node

playingPlayers

integer

required

The number of players currently playing a track

uptime

integer

required

The uptime of the node in milliseconds

memory

object

required

Memory statistics for the node

Show Memory Properties

free

integer

required

The amount of free memory in bytes

used

integer

required

The amount of used memory in bytes

allocated

integer

required

The amount of allocated memory in bytes

reservable

integer

required

The amount of reservable memory in bytes

cpu

object

required

CPU statistics for the node

Show CPU Properties

cores

integer

required

The number of CPU cores available to the node

systemLoad

float

required

The system-wide CPU load (0.0 to 1.0+)

lavalinkLoad

float

required

The CPU load from Lavalink specifically (0.0 to 1.0+)

frameStats

object

Frame statistics (null if no players or when retrieved via /v4/stats REST endpoint)

Show Frame Stats Properties

sent

integer

required

The number of frames sent to Discord

nulled

integer

required

The number of frames that were nulled

deficit

integer

required

The difference between sent frames and expected frames. Expected is 3000 per player (1 every 20ms). Negative means too many frames sent, positive means not enough.

{
  "op": "stats",
  "players": 1,
  "playingPlayers": 1,
  "uptime": 123456789,
  "memory": {
    "free": 123456789,
    "used": 123456789,
    "allocated": 123456789,
    "reservable": 123456789
  },
  "cpu": {
    "cores": 4,
    "systemLoad": 0.5,
    "lavalinkLoad": 0.5
  },
  "frameStats": {
    "sent": 6000,
    "nulled": 10,
    "deficit": -3010
  }
}

Event OP

Dispatched when player or voice events occur.

string

required

Always "event"

type

string

required

The event type. One of: TrackStartEvent, TrackEndEvent, TrackExceptionEvent, TrackStuckEvent, WebSocketClosedEvent

guildId

string

required

The Discord guild ID where the event occurred

Event Types

TrackStartEvent

Dispatched when a track starts playing.

track

object

required

The track that started playing

Show Track Properties

encoded

string

required

Base64 encoded track data

info

object

required

Track metadata

Show Track Info Properties

identifier

string

required

The track identifier (e.g., YouTube video ID)

isSeekable

boolean

required

Whether the track supports seeking

author

string

required

The track author/artist

length

integer

required

The track length in milliseconds

isStream

boolean

required

Whether the track is a live stream

position

integer

required

The current position in milliseconds

title

string

required

The track title

uri

string

The track URI/URL

artworkUrl

string

URL to the track’s artwork/thumbnail

isrc

string

The International Standard Recording Code

sourceName

string

required

The source platform (e.g., “youtube”, “soundcloud”)

pluginInfo

object

required

Additional data provided by plugins

{
  "op": "event",
  "type": "TrackStartEvent",
  "guildId": "817327181659111454",
  "track": {
    "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==",
    "info": {
      "identifier": "dQw4w9WgXcQ",
      "isSeekable": true,
      "author": "RickAstleyVEVO",
      "length": 212000,
      "isStream": false,
      "position": 0,
      "title": "Rick Astley - Never Gonna Give You Up",
      "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "isrc": null,
      "sourceName": "youtube"
    },
    "pluginInfo": {}
  }
}

TrackEndEvent

Dispatched when a track finishes playing or is stopped.

track

object

required

The track that ended (same structure as TrackStartEvent)

reason

string

required

The reason the track ended:

finished - The track completed normally (may start next: true)
loadFailed - The track failed to load (may start next: true)
stopped - The track was manually stopped (may start next: false)
replaced - The track was replaced by another (may start next: false)
cleanup - The track was cleaned up (may start next: false)

{
  "op": "event",
  "type": "TrackEndEvent",
  "guildId": "817327181659111454",
  "track": {
    "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5...",
    "info": { /* ... */ }
  },
  "reason": "finished"
}

TrackExceptionEvent

Dispatched when a track throws an exception during playback.

track

object

required

The track that threw the exception

exception

object

required

The exception details

Show Exception Properties

message

string

The exception message

severity

string

required

The severity level:

common - Known and expected cause, nothing wrong with the library
suspicious - Possibly caused by external factors or unexpected response format
fault - Likely a library issue or unknown cause (default level)

cause

string

required

The cause of the exception

causeStackTrace

string

required

The full stack trace of the exception cause

{
  "op": "event",
  "type": "TrackExceptionEvent",
  "guildId": "817327181659111454",
  "track": {
    "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5...",
    "info": { /* ... */ }
  },
  "exception": {
    "message": "Something went wrong",
    "severity": "common",
    "cause": "Error details",
    "causeStackTrace": "Full stack trace..."
  }
}

TrackStuckEvent

Dispatched when a track gets stuck while playing.

track

object

required

The track that got stuck

thresholdMs

integer

required

The threshold in milliseconds that was exceeded

{
  "op": "event",
  "type": "TrackStuckEvent",
  "guildId": "817327181659111454",
  "track": {
    "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5...",
    "info": { /* ... */ }
  },
  "thresholdMs": 123456789
}

WebSocketClosedEvent

Dispatched when the Discord voice WebSocket connection closes. This can happen for various reasons. 4xxx codes typically indicate serious issues.

code

integer

required

The Discord close event code

reason

string

required

The human-readable close reason

byRemote

boolean

required

Whether the connection was closed by Discord (true) or locally (false)

{
  "op": "event",
  "type": "WebSocketClosedEvent",
  "guildId": "817327181659111454",
  "code": 4006,
  "reason": "Your session is no longer valid.",
  "byRemote": true
}

For more information on Discord voice close codes, see the Discord Voice Close Event Codes documentation.

Overview

Endpoints

Plugin Development

Overview

Connection Setup

Opening a Connection

Required Headers

Example Connection Headers

Message Format

OP Types

Ready OP

Player Update OP

Stats OP

Event OP

Event Types

TrackStartEvent

TrackEndEvent

TrackExceptionEvent

TrackStuckEvent

WebSocketClosedEvent

Build docs developers (and LLMs) love

Overview

Endpoints

Plugin Development

​Overview

​Connection Setup

​Opening a Connection

​Required Headers

​Example Connection Headers

​Message Format

​OP Types

​Ready OP

​Player Update OP

​Stats OP

​Event OP

​Event Types

​TrackStartEvent

​TrackEndEvent

​TrackExceptionEvent

​TrackStuckEvent

​WebSocketClosedEvent

Build docs developers (and LLMs) love

Overview

Connection Setup

Opening a Connection

Required Headers

Example Connection Headers

Message Format

OP Types

Ready OP

Player Update OP

Stats OP

Event OP

Event Types

TrackStartEvent

TrackEndEvent

TrackExceptionEvent

TrackStuckEvent

WebSocketClosedEvent