Skip to content

WebSocket API

Jump to bottom
Thomas Gaubert edited this page Jul 26, 2016 · 12 revisions

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.

Organization

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. Refer to the Payloads wiki page for full documentation on a payload's fields.

Payloads are sent as Strings at all times.

Visibility

Payload responses from the server may be either public or private.

  • Public payloads are transmitted on the Socket.IO event as documented, which allows for any and all connected clients to see the contents of the message.
  • Private payloads are transmitted on a Socket.IO event that corresponds to the from field in the metadata object of the payload.

Note that the word "response" is used loosely as responses may not necessarily be prompted by a payload of the same type sent by the client.

Events

Below are the events and payload types covered by the public API. Additional events 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.

Version (version)

These events relate to version information of the server and clients.

Version info

Payload type: version

Response visibility: private

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)

These events relate to notifications.

Display notification

Payload type: notification

Response visibility: public

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

Response visibility: private

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-response',
    from: 'server',
    to: 'client'
},
payload: {
    result: true,
    resultCode: 0,
    resultMessage: 'Success',
    id: 0
}

Devices (devices)

These events relate to information regarding devices currently connected to the server.

Add device

Payload type: devices-add

Response visibility: public

Used to notify clients of a connected device.

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 device connects to the server by responding to a ping broadcast (broadcast-ping).

metadata: {
    version: 1,
    type: 'devices-add',
    from: 'server',
    to: ''
},
payload: {
    name: b.metadata.from
}

Clear devices

Payload type: devices-clear

Response visibility: public

Used to notify clients to clear their local list of currently connected devices.

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 device disconnects from the server. The server will then send out a ping broadcast and any subsequent devices-add payloads.

metadata: {
    version: 1,
    type: 'devices-clear',
    from: 'server',
    to: ''
},
payload: { }

Broadcast (broadcast)

These events are intended for all clients.

Shutdown

Payload type: broadcast-shutdown

Response visibility: public

Used to indicate that the server is shutting down.

Sending

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

Receiving

The server will send this payload immediately before shutting down.

metadata: {
    version: 1,
    type: 'broadcast-shutdown',
    from: 'server',
    to: ''
},
payload: { }

Overlay not running

Payload type: broadcast-overlay-not-running

Response visibility: public

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

Sending

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

Receiving

The server will send this payload when the OpenVR overlay fails to launch or dies unexpectedly.

metadata: {
    version: 1,
    type: 'broadcast-overlay-not-running',
    from: 'server',
    to: ''
},
payload: {
    message: 'Overlay is no longer running.',
    error: error
}

Ping

Payload type: broadcast-ping

Response visibility: public

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

Sending

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

Receiving

The server will send this payload when a client disconnects or if a client sends a version payload. A client which receives this message should send a broadcast-pong payload.

metadata: {
    version: 1,
    type: 'broadcast-ping',
    from: 'server',
    to: ''
},
payload: { }

Ping

Payload type: broadcast-ping

Response visibility: not applicable

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

Sending

This payload should be sent to the server in response to a broadcast-ping payload.

Note: Sending this payload to the server will result in the server sending the to field within the metadata object to all clients as part of a devices-add payload. This results in your client to show up as a connected device.

metadata: {
    version: 1,
    type: 'broadcast-pong',
    from: 'client',
    to: ''
},
payload: { }
Receiving

The server will not send this payload, so there is no need to handle such a case.

Clone this wiki locally