XSOverlay WebSocket API
XSOverlay has a WebSocket based API for interacting with the Notifications, SteamVR, and the overlay itself.
Configuration
XSOverlay, by default, is configured to listen for WebSocket messages on port 42070
. This can be changed by editing the ExternalMessageAPIConfig.json
file located in the [XSOverlayInstallDirectory]/XSOverlay_Data/StreamingAssets/Plugins/Config/
directory.
The following options can be configured:
Option | Description | Default Value |
---|---|---|
WebSocketPort | The port XSOverlay listens to WebSocket messages on. | 42070 |
XSOverlay ONLY listens for messages from the local host. You CANNOT currently send messages over the network to a different machine
API Object / Message Format
All WebSocket messages are sent as JSON objects. The following properties are available:
Property | Data Type | Description |
---|---|---|
sender | string | The name of the application sending the message |
target | string | The name of the application the message is intended for. Ex 'xsoverlay' |
command | string | The command to issue to the target |
jsonData | string | JSON Payload with command specific data. See below for endpoint specific for endpoint message formats |
rawData | string | Raw data payload with a singular value in string format like "true", "false", etc. This is mainly used by the UI to do things like setting settings, where the string will be parsed |
Connecting to the WebSocket
A C# example of connecting to the XSOverlay WebSocket server. This is a C# example, but the same concept can be applied to any language that supports WebSocket and JSON serialization.
You must include client
as a query string in your websocket url. If you do not, the connection will be ignored. e.g. we://host:port/?client=ClientName
static async Task Main(string[] args)
{
WebsocketPort = (args.Length == 0) ? 42070 : Int32.Parse(args[0]);
var exitEvent = new ManualResetEvent(false);
var wsURL = new Uri($"ws://localhost:{WebsocketPort}/?client=[YOURAPPNAMEHERE]");
// The format of this URL is very important. Client token needs to be there and should be the name of your application, if a client token is not present, the server will reject the connection.
// If a client token is already in use, the server will simply add it to a list. This means that if anything sends a message to your client token, it will be sent to everything in that list for the token.
using (Socket = new WebsocketClient(wsURL))
{
Socket.Start();
}
}
Sending a command
After connecting to the websocket, youll likely want to send a command. Below is an example of how to send a notification via the websocket API. See API Commands for a list of api commands.
void foobar()
{
XSONotificationObject notification = new XSONotificationObject(); // See WebsocketAPI / XSONotificationObject for more information
notification.title = "woah its an example!";
notification.type = 1;
XSOApiObject apiObject = new XSOApiObject(); // See WebsocketAPI / XSOApiObject for more information
apiObject.sender = "xsoverlay";
apiObject.target = target;
apiObject.command = "SendNotification";
apiObject.jsonData = JsonSerializer.Serialize(notification);
apiObject.rawData = null;
ws.Send(JsonSerializer.Serialize(apiObject));
}
Subscribing to Events
Note that subscription tag name is parsed from an enum internally. Spelling matters. Casing is ignored.
Some API events allow you to subscribe to them by passing an array of tags in the jsonData
field in XSOApiObject
.
This is useful if you want to continuously get up-to-date information about something without sending a message each time you want an update.
Below you will find a list of available subscription tags, what commands they would map to, and an example of how to subscribe to those tags.
Subscription Tags
Tag Name | Event |
---|---|
DateAndTime | RequestDateTime |
DeviceInformation | RequestDeviceInformation |
Theme | RequestThemeUpdate |
LayoutMode | RequestLayoutModeState |
MediaPlayer | RequestMediaPlayerUpdate |
Languages | RequestUpdatedLanguageList |
LanguageMap | RequestUpdatedLanguageMap |
WindowList | RequestWindowList |
ActiveOverlay | RequestActiveOverlayInformation |
Settings | RequestGetSettings |
Performance | RequestRuntimePerformance |
Example
void foobar()
{
List<string> tags = new List<string>()
{
"Theme",
"DateAndTime",
// ... etc
};
XSOApiObject apiObject = new XSOApiObject(); // See WebsocketAPI / XSOApiObject for more information
apiObject.sender = "xsoverlay";
apiObject.target = target;
apiObject.command = "SubscribeToEvents";
apiObject.jsonData = JsonSerializer.Serialize(tags);
ws.Send(JsonSerializer.Serialize(apiObject));
}
Unsubscribing to Events
Unsubscribing to events is the same as subscribing, except you send the UnsubscribeToEvents
command instead of SubscribeToEvents
.