WebSocket API

API Version: 1

---

Zephyr's WebSocket API provides a means of communicating with Zephyr. Check out the REST API if you're looking to only show notifications through Zephyr.

Zephyr uses Socket.IO to communicate over WebSockets. It's recommended that you use one of Socket.IO's libraries to get up and running as fast as possible.

Requests are made over port 3753 on localhost or the IP address reported in the main Zephyr window.

Events

Zephyr's components are broken up into Socket.IO events (the name of the event is denoted in parentheses). Each event may have several payload types, as outlined below.

Payload types may have different behavior depending if the payload is being sent to or received from the server.

Version (version)

Version info

Payload type: version

Used to transmit version information.

Sending

Sending this payload to the server will result in the server logging your client's version info and replying with the server's version information.

metadata: {
    version: 1,
    type: 'version',
    from: 'client',
    to: ''
},
payload: {
    name: 'Zephyr Client',
    version: '1.0.0',
    versionCode: 1,
    versions: [
        {
            name: 'custom-version',
            value: 2
        }
    ]
}

Receiving

The server will send this payload after a version payload is received by the server from your client.

metadata: {
    version: 1,
    type: 'version',
    from: 'server',
    to: 'client'
},
payload: {
    name: 'Zephyr Server',
    version: '1.0.0',
    versionCode: 1,
    versions: [
        {
            name: 'platform',
            value: process.platform
        },
        {
            name: 'node',
            value: process.version
        }
    ]
}

Notifications (notification)

Display notification

Payload type: notification

Used to display a notification.

Sending

Sending this payload to the server will result in the server broadcasting the notification to all other clients (including the Zephyr OpenVR overlay) so it can be displayed.

The server will send a notification response in reply.

metadata: {
    version: 1,
    type: 'notification',
    from: 'client',
    to: ''
},
payload: {
    id: 0,
    title: 'Test Notification',
    text: 'This is a test notification.',
    device: 'Zephyr Client'
}

Receiving

The server will send this payload after a notification was sent to the server by a client. Note that this includes notifications sent from the same client (filter based on the from metadata field).

metadata: {
    version: 1,
    type: 'notification',
    from: 'client',
    to: ''
},
payload: {
    id: 0,
    title: 'Test Notification',
    text: 'This is a test notification.',
    device: 'Zephyr Client'
}

Confirming notification creation

Payload type: notification-response

Used to inform a client which created a notification of the respective notification's status.

Note: Notification response will always report successful. This behavior will change in a future release. Refer to the notification-response payload for more information.

Sending

Sending this payload is not supported and will not result in any action from the server.

Receiving

The server will send this payload after a notification was sent to the server by the client.

metadata: {
    version: 1,
    type: 'notification',
    from: 'client',
    to: ''
},
payload: {
    result: true,
    resultCode: 0,
    resultMessage: 'Success',
    id: 0
}