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.

Debugging API Commands