WebSocket API

Address: ws://127.0.0.1:44555 on the MyHUD PC. From another device: ws://<address>:44555/?token=<token>.

Use the WebSocket when you want to:

• receive changes and game events as they happen;
• send many commands on one connection.

All messages are JSON objects with a type field.

Connection

1. Connect.
2. If you connect from another device without a token in the URL, send auth within 5 seconds.
3. MyHUD sends welcome with the current state.
4. If you want other channels than the default ones, send subscribe.

{
  "type": "welcome",
  "protocolVersion": 2,
  "revision": 42,
  "authenticated": true,
  "state": { "revision": 42, "vetoVisible": true, "hudWindowOpen": true }
}

Messages you send

trigger

Runs a command.

{ "type": "trigger", "action": "set_event_name", "payload": { "name": "Spring Cup" }, "correlationId": "42" }

• payload: optional, same as the HTTP body.
• correlationId: optional. MyHUD puts it in the ack, so you can match the answer with the request.

Send one command at a time on a connection: wait for the ack before you send the next trigger. Otherwise MyHUD answers with the error busy.

subscribe

Chooses the channels you receive.

{ "type": "subscribe", "channels": ["state", "app", "game"] }

MyHUD answers with subscribed. Unknown channel names are listed in ignored.

auth

Sends the token, if it is not in the URL.

{ "type": "auth", "token": "<token>" }

MyHUD answers authenticated, then welcome.

resume

After a reconnection, gives the last revision you received. If the state changed since, MyHUD sends a state message.

{ "type": "resume", "lastRevision": 42 }

ping

{ "type": "ping", "t": 1712345678 }

MyHUD answers { "type": "pong", "t": 1712345678 }.

Messages you receive

ack

The answer to a trigger.

{ "type": "ack", "correlationId": "42", "ok": true, "state": { "revision": 43 }, "result": {} }

On failure:

{ "type": "ack", "correlationId": "42", "ok": false, "error": "No veto in progress", "code": "conflict" }

error is the message, and code is the error code.

state

A change of the HUD state. patch contains only the fields that changed.

{ "type": "state", "revision": 43, "patch": { "vetoVisible": false } }

event

{ "type": "event", "name": "veto_updated", "data": { "action": "veto_select" } }

error

A message that MyHUD could not process, or a command sent while another one is in progress.

{ "type": "error", "code": "busy", "message": "Another command is in progress on this connection" }

Channels

Channel	Messages	Default
state	state: visibility of the HUD panels, roster.	yes
app	event: changes made through the API.	yes
game	event: what happens in the game.	no

If you never send subscribe, you receive state and app.

app events

Event	When	data
overlay_reloaded	The overlay was reloaded.	—
hud_visibility_changed	The overlay window was opened or closed.	—
veto_imported	A veto was imported and applied.	provider, teamA, teamB, boFormat, shown
veto_updated	A veto command changed the veto.	action: the command name
match_updated	The teams, the event name, the team size or a score changed.	match: the match summary
sen_scene_changed	The scene window changed scene, or closed.	scene, or null

MyHUD sends these events after commands from the API (from any client). It does not send them when you change the same thing in the MyHUD window.

game events

See React to game events.

Event	data
match_live	scoreboard
round_end	scoreboard + winner
bomb_planted	scoreboard
half_time	scoreboard
map_end	scoreboard + winner

The scoreboard is { map, round, scoreCT, scoreT, teamCT, teamT }.

Close codes

Code	Reason
4401	unauthorized: wrong token. auth_timeout: no auth within 5 seconds.
4403	local_only: local network mode is off. forbidden_origin: connection from a web page. invalid_host: invalid address.

MyHUD also closes all connections when it restarts, or when you change the automation settings.