WebSocket commands and responses

WebSocket commands and responses

Technical info below! This is only important to you if you are considering creating a new client or if you want to extend WebConsole possibilities. Below is a detailed list containing all current WebConsole commands, along with the data that the server will send in response to these commands.

Commands

Before v2.1, commands were only a String containing the command, plus a space and any parameter. Now, they are inside a JSON String. If you are using v2.0-rev3 or older, please check out this wiki page

LOGIN

Logs user in into server. This is the first command client should send to server. Login is required in order to run any of the other commands.

Available since: v1.0
Example usage: {"command":"LOGIN", "params":"myPassw0rd"}

Responds with:

• 200 If password was correct
• 401 If password was incorrect

EXEC (command)

Execute a command into the Minecraft Server console as if you were typing into the real console.

Available since: v1.0
Example usage: {command: "EXEC", token: "75dc2171-6d59-4784-9b8e-823209ca765d", params: "say Hello from WebConsole!"}

Responds with:
This message does not generate a response itself, but WebConsole will send you the console output generated for your command with a 010 message.

PLAYERS

Ask server for the number of connected and total players.

Available since: v1.1
Example usage: {command: "PLAYERS", token: "75dc2171-6d59-4784-9b8e-823209ca765d"}

Responds with:
1000 Players object

CPUUSAGE

Ask server for the CPU usage percentage.

Available since: v1.1
Example usage: {command: "CPUUSAGE", token: "75dc2171-6d59-4784-9b8e-823209ca765d"}

Responds with:
1001 CPUUsage object

RAMUSAGE

Ask server for the amount of free, used and total RAM for that Java VM instance.

Available since: v1.1
Example usage: {command: "RAMUSAGE", token: "75dc2171-6d59-4784-9b8e-823209ca765d"}

Responds with:
1002 RAMUsage object

TPS

Ask server for current TPS.

Available since: v2.4
Example usage: {command: "TPS", token: "75dc2171-6d59-4784-9b8e-823209ca765d"}

Responds with:
1003 TPS object

READLOGFILE

Ask server for the full latest.log file.

Available since: v1.5
Example usage: {command: "READLOGFILE", token: "75dc2171-6d59-4784-9b8e-823209ca765d"}

Responds with:
This message does not generate a response itself, instead WebConsole will send you all the lines inside latest.log as 010 messages (one message per line).

Responses

All responses are sent into a JSON string. Every response will contain a status and statusDescription parameter to allow the client know the response type. All possibilities are shown below.

010 Console Output

Sends a line printed in Minecraft console.

Available since: v1.0

Extra parameters:

• time: String that contains HH:mm:ss (hour:minute:seconds) when this line was printed OR null if a time prefix is already printed. Since v1.6
• message: Contains the console line printed into real console.

Example response:

{status: 10, statusDescription: "Console Output", time: "10:05:50", message: "[Server] Hello from WebConsole!"}

200 LoggedIn

Tells the client that a previously sended LOGIN command was successful.

Available since: v1.0

Extra parameters:

• respondsTo: Command that originated this response.
• username: Username of the user logged in.
• as: Type of user (ADMIN or VIEWER).
• token: Token for this connection. You will need to send this token inside all of your next commands or the server will quietly reject your command.
• message: User-readable message for this object.

Example response:

{status:200, statusDescription:"LoggedIn", as:"ADMIN", token:"75dc2171-6d59-4784-9b8e-823209ca765d", respondsTo:"LOGIN ********", message:"Logged In"}

400 Unknown Command

A sent command does not exist or was not understood by server.

Available since: v1.0

Extra parameters:

• respondsTo: Command that originated this response.
• message: User-readable message for this object.

Example response:

{status: 400, statusDescription: "Unknown Command", respondsTo: "ESEC esec command do not exist!", message: "Unknown command"}

401 Login Required

First message that client will receive when connecting to a server. Informs that login is required with a valid password in order to start executing commands.

Available since: v1.0

Extra parameters:

• message: User-readable message for this object.

Example response:

{status: 401, statusDescription: "Login Required", message: "Connection started, waiting login"}

1000 Players

Retrieves number of connected and total players in the server

Available since: v1.1

Extra parameters:

• connectedPlayers: Number of connected players.
• maxPlayers: Maximum number of player slots.
• players: List of connected users (nickname). Since v1.3
• message: User-readable message for this object.

Example response:

{status: 1000, statusDescription: "Players", connectedPlayers: 0, maxPlayers: 20, message: "Currently 0 connected players for a maximum of 20"}

1001 CPU Usage

Retrieves percentage of CPU used by the host machine.

Available since: v1.1

Extra parameters:

• usage: Percentage of CPU used by the host machine.
• message: User-readable message for this object.

Example response:

{status: 1001, statusDescription: "CPU Usage", usage: 8.7, message: "Usage is 8.7%"}

1002 RAM Usage

Retrieves amount of free, used and total RAM for that Java VM instance.

Available since: v1.1

Extra parameters:

• free: Free amount of memory.
• used: Used amount of memory.
• max: Maximum amount of memory.
• message: User-readable message for this object.

Example response:

{"status":1002,"statusDescription":"RAM Usage","free":471,"used":519,"max":990,"message":"471 free, 519 used, 990 maximum memory"}

1003 TPS

Retrieves TPS info.

Available since: v2.4

Extra parameters:

• tps: Current TPS.
• message: User-readable message for this object.

Example response:

{"status":1003,"statusDescription":"TPS","tps":19,"message":"TPS 19"}