Payloads

API Version: 1

---

Overview

Payloads are bundles of content that are used throughout the project, including in the REST and WebSocket APIs. Payloads are always represented as JSON objects (though note that payloads are transmitted as Strings via the APIs). All payloads are made up of the following components:

• Metadata - information about payload type, version, etc.
• Payload - information being transferred as part of the payload

The payloads described here are those which apply to either the public REST or WebSocket APIs. Additional endpoints and their associated payloads are used internally, but use of these is at your own risk as they may change independently of the public API.

Metadata

Metadata content is consistent between all payload types, ensuring that each component of the system can verify the payload.

metadata: {
    version: 1,        // Payload schema version
    type: 'version',   // Payload schema type
    from: 'server',    // Payload origin
    to: 'client'       // Payload destination
}

The version and type fields are determined by the payload's JSON payload object following the metadata (described below). The from field value is determined by the sender (it should choose a constant ID). The to field value is generally less important and is primarily used when responding to another payload (by using the from field of that payload). In other cases, it's okay for the to field to be an empty String.

Payload types

The value denoted in parentheses indicates the type field contained within the metadata object as described above.

Version (version)

Used to transmit version information.

payload: {
    name: 'Zephyr Server',   // App name
    version: '1.0.0',        // App version
    versionCode: 1,          // App version code
    versions: [              // Additional custom versions (in this case, for the desktop client)
        {
            name: 'platform',
            value: process.platform
        },
        {
            name: 'node',
            value: process.version
        }
    ]
}

Notifications

Used to transmit notification information.

Notification (notification)

Used to display a new notification.

payload: {
    id: 0,                                  // Unique ID, to be used when sending Notification response
    title: 'Test Notification',             // Notification title
    text: 'This is a test notification.',   // Notification text
    device: 'Zephyr Desktop Client'         // Source sending the notification (not currently displayed) 
}

Notification response (notification-response)

Used alert client sending notification if notification was shown successfully.

Note: Notification response will always report successful. This behavior will change in a future release.

payload: {
    result: true,               // True if notification was successfully displayed
    resultCode: 0,              // Result code (documented below)
    resultMessage: 'Success',   // Result message
    id: n.payload.id            // ID of relevant notification (as set when sending the notification)
}

Result codes

Note: Notification response will always report successful. This behavior will change in a future release and additional result codes will be added.

• 0 - Success

Devices

Used to update clients about currently connected devices.

Device added (devices-add)

Used to indicate when a device has connected to the server.

payload: {
    name: b.metadata.from   // Name of device
}

Clear devices (devices-clear)

Used to indicate when a device has disconnected and any lists of currently connected devices need to be rebuilt (using a ping broadcast).

payload: { }   // Empty payload body

Broadcast

Broadcasts are used for quick messages intended for all clients.

Shutdown (broadcast-shutdown)

Used to indicate that the server is shutting down.

payload: { }   // Empty payload body

Overlay not running (broadcast-overlay-not-running)

Used to indicate that the OpenVR overlay isn't running.

payload: {
    message: 'Overlay is no longer running.',   // Error message
    error: error                                // Error object as reported by desktop client
}

Ping (broadcast-ping)

Used to request a pong response to see which clients are currently connected to the server.

payload: { }   // Empty payload body

Pong (broadcast-pong)

Used in response to a ping.

payload: { }   // Empty payload body