Airzone Cloud Websocket API 1.0.0



Introduction

The following document describes the use of the Airzone Cloud Websocket API. The Websocket API provides a push interface for user and device related events. Its use is intended to be done when using the Web API. To fully understand the API, please refer to the Web API.

Two different stages can be identified:

  • Initial connection

  • Authentication periodic check

Initial connection

Airzone's Cloud Websocket API allows the subscription to user related events and installation related events.

Subscription to User specific events

To start receiving user related events, it is needed to establish a Secure WebSocket connection (WSS) through the following URL:

m.airzonecloud.com/api/v1/websockets/user
When establishing the WebSocket connection, the server will automatically subscribe the client to the USER and INSTALLATION namespace default events, specifically the following events (please refer to the API for details of each event):

User namespace:

  • USERS.update
  • USERS.delete
  • USERS.completed-user-invitation

Installation namespace:

  • INSTALLATIONS.user-deleted-installation
  • INSTALLATIONS.user-invited-installations
  • INSTALLATIONS.user-confirmed-installation
  • INSTALLATIONS.user-deleted-installation-invitation

workflow

The following image describes the intented use of the websocket API: Websocket API user flow

Subscription to Site specific events

To start receiving site's devices related events, it is needed to establish a Secure WebSocket connection (WSS) through the following URL:

m.airzonecloud.com/api/v1/websockets/installation?installationId={yourInstallationId}
These events are related to the user's account, and are independent of any Site the user belongs to. For installation's devices related URL. the server will automatically subscribe the client to INSTALLATION, WEBSERVER_UPDATES and DEVICES_UPDATES namespaces described events, specifically the following events (please refer to the API for details of each event):

The server will start sending the following events associated with the Site and the devices included in items:

Installation namespace:

  • INSTALLATIONS.delete-ws
  • INSTALLATIONS.added-ws-installation
  • INSTALLATIONS.installation-updated-discovery
  • INSTALLATIONS.devices-moved-group
  • INSTALLATIONS.edit-installation-location
  • INSTALLATIONS.edit-installation-meta
  • INSTALLATIONS.user-edit-permission-installation
  • INSTALLATIONS.started-exec-scene
  • INSTALLATIONS.finishedExecScene

Webserver's changes namespace:

  • WEBSERVER_UPDATES.{wsId}

Device's changes namespace:

  • DEVICES_UPDATES.{wsId}.{deviceId}

Then, the server will send the current state of each device belonging to the site, through DEVICE_STATE events. This is useful to have a current snapshot of the site's devices. Once sent the state for every device, a DEVICE_STATE_END event will be sent.

workflow

The following image describes the intented use of the websocket API: Websocket API installation flow

Authentication periodic check

Once the user establishes the websocket connection, a periodic auth event will be sent from the server. Upon receiving the event, the user must respond with its current authentication token (same token used in the Authorization header for the Web API requests). Websocket API Auth flow

Serve will send a correlation id field that identifies the request. Client should send jwt data with the receiving correlation id with the following format:

{
  corrId: <request corrId>
  body: {
    jwt: <user jwt token>
  }
}

Server will close the connection in the following cases:

  • Client dont send JWT authentication response in the following 5 seconds.
  • In case of the token being invalid (expired or invalidated), the server will close the connection. The user will need to obtain a new valid token and reestablish the connection.

In such cases, server will append to close event a 4001 status code and a description message.

workflow

The following image describes the intented use of the websocket API: Websocket API Auth flow In case of needing to listen to multiple sites at the same time, one independent websocket connection per each site should be established.

Code examples

Below are two example codes by which a websocket client can listen to airzone user events and installation events.

User events

const jwt = <your jwt token> const client = new WebSocket('wss://devazglobal.airzonecloud.com/api/v1/websockets/user', {
  headers: {
    Authorization: `Bearer ${jwt}`,
  },
  rejectUnauthorized: false,
});
client.on('open', () => {
  console.info('Airzone WS connection established');
});
// Helper function to handle message parsing
const parseMessage = (message) => {
  try {
    return JSON.parse(message.toString());
  } catch (error) {
    console.error('Failed to parse message', { error });
    return null;
  }
};
client.on('message', async (message) => {
  const data = parseMessage(message);
  if (!data) return;
  switch (data.event) {
    case 'auth': {
      const response = { corrId: data.corrId, body: { jwt } };
      client.send(JSON.stringify(response));
      break;
    }
    case 'USER.update': {
      // Handle event here
      break;
    }
    case 'USERS.delete': {
      // Handle event here
      break;
    }
    case 'USERS.completed-user-invitation': {
      // Handle event here
      break;
    }
    // Handle other events here ...

    default:
      console.warn('Received unknown message', { message: data.body });
      break;
  }
});
client.on('error', (error) => {
  console.error(`Airzone WS connection error: ${new Date().toISOString()} ${error}`);
});
client.on('close', (code, reason) => {
  console.info(`Airzone WS connection closed: ${new Date().toISOString()} Code: ${code}, Reason: ${reason}`);
});

Installation events


    const jwt = <your jwt token>
    const client = new WebSocket('wss://devazglobal.airzonecloud.com/api/v1/websockets/installation?installationId=64184eb48e68ffbe3a94cadc', {
      headers: {
        Authorization: `Bearer ${jwt}`,
      },
      rejectUnauthorized: false,
    });

    client.on('open', () => {
      console.info('Airzone WS connection established');
    });

    // Helper function to handle message parsing
    const parseMessage = (message) => {
      try {
        return JSON.parse(message.toString());
      } catch (error) {
        console.error('Failed to parse message', { error });
        return null;
      }
    };

    client.on('message', async (message) => {
      const data = parseMessage(message);
      if (!data) return;
      switch (data.event) {
        case 'auth': {
          const response = { corrId: data.corrId, body: { jwt } };
          client.send(JSON.stringify(response));
          break;
        }
        case 'DEVICES_UPDATES.{yourWsId}.{yourDeviceId}': {
          // Handle event here
          break;
        }
        case 'INSTALLATIONS.started-exec-scene': {
          // Handle event here
          break;
        }
        case 'INSTALLATIONS.user-edit-permission-installation': {
          // Handle event here
          break;
        }
        // Handle other events here ...

        default:
          console.warn('Received unknown message', { message: data.body });
          break;
      }
    });

    client.on('error', (error) => {
      console.error(`Airzone WS connection error: ${new Date().toISOString()} ${error}`);
    });

    client.on('close', (code, reason) => {
      console.info(`Airzone WS connection closed: ${new Date().toISOString()} Code: ${code}, Reason: ${reason}`);
    });

This page can also be downloaded in AsyncAPI format through this link.

  • #User
  • #Installation
  • #Auth

Servers

  • m.airzonecloud.com/api/v1/websocketswssproduction

    Production server

    Security:
    • HTTP
      • Scheme: bearer
      • Bearer format: JWT

Operations

  • SUB user

    Channel where user events are published.

    Operation IDpublish

    Available only on servers:

    object
    • #Auth

    Accepts the following message:

    User's JWT authentication response.AuthMsgResponse
    Message IDAuthMsgResponse

    Event to authenticate user in periodic authentication check.

    restricted any allOf
    • #Auth

    Examples

  • PUB user

    Channel where user events are published.

    Operation IDsubscribe

    Available only on servers:

    object
    • #User

    Accepts one of the following messages:

    • #0User's settings updatedUSERS.update

      Event indicating the user has updated his settings

      Message IDUSERS.update

      This event is fired upon any change the user makes in his account's settings.

      restricted any allOf
      • #User

      Examples

    • #1User's account deletedUSERS.delete

      Event indicating the user's account has been deleted

      Message IDUSERS.delete

      This event is fired when the user has deleted his account. This will automatically close the channel.

      restricted any allOf
      • #User

      Examples

    • #2User's completed an invitationUSERS.completed-user-invitation
      Message IDUSERS.completed-user-invitation

      Event indicating that user completed an invitation

      restricted any allOf
      • #User

      Examples

    • #3User's account deletedINSTALLATIONS.user-deleted-installation
      Message IDINSTALLATIONS.user-deleted-installation

      Event for informing of user being removed from an installation

      restricted any allOf
      • #User

      Examples

    • #4User's invited to an installationINSTALLATIONS.user-invited-installations
      Message IDINSTALLATIONS.user-invited-installations

      Event for informing of user being invited to a new installation

      restricted any allOf
      • #User

      Examples

    • #5User's confirmed an invitation to an installationINSTALLATIONS.user-confirmed-installation
      Message IDINSTALLATIONS.user-confirmed-installation

      Event for informing of user confirmed an invitation to an installation

      restricted any allOf
      • #User

      Examples

    • #6User's rejected/deleted an invitation to an installationINSTALLATIONS.user-deleted-installation-invitation
      Message IDINSTALLATIONS.user-deleted-installation-invitation

      Event for informing of rejection/deletion of an invitation to an installation

      restricted any allOf
      • #User

      Examples

    • #7User's JWT authentication request.

      Event to authenticate user in periodic authentication check.

      restricted any allOf
      • #Auth

      Examples

  • SUB installation

    Channel where related installations events are published.

    Operation IDpublish

    Available only on servers:

    object
    installationId
    required
    string

    site's installation_id

    object
    • #Auth

    Accepts the following message:

    User's JWT authentication response.AuthMsgResponse
    Message IDAuthMsgResponse

    Event to authenticate user in periodic authentication check.

    restricted any allOf
    • #Auth

    Examples

  • PUB installation

    Channel where related installations events are published.

    Operation IDsubscribe

    Available only on servers:

    object
    installationId
    required
    string

    site's installation_id

    object
    • #Installation

    Accepts one of the following messages:

    • #0User's webserver has been deletedINSTALLATIONS.deleted-ws
      Message IDINSTALLATIONS.deleted-ws

      Event for informing that a webserver has been deleted.

      restricted any allOf
      • #User

      Examples

    • #1User's scene has been executedINSTALLATIONS.finished-exec-scene
      Message IDINSTALLATIONS.finished-exec-scene

      Event for informing the ending of the execution of an scene

      restricted any allOf
      • #Installation

      Examples

    • #2User's scene has been executedINSTALLATIONS.started-exec-scene
      Message IDINSTALLATIONS.started-exec-scene

      Event for informing the ending of the execution of an scene

      restricted any allOf
      • #Installation

      Examples

    • #3User's installation permissions access has been changedINSTALLATIONS.user-edit-permission-installation
      Message IDINSTALLATIONS.user-edit-permission-installation

      Event for informing changes in the user's permission access in an installation

      restricted any allOf
      • #Installation

      Examples

    • #4User's installation metaparameters has changed.INSTALLATIONS.edit-installation-meta
      Message IDINSTALLATIONS.edit-installation-meta

      Event for informing changes in the installation's metaparameters

      restricted any allOf
      • #Installation

      Examples

    • #5User's installation location has changed.INSTALLATIONS.edit-installation-location
      Message IDINSTALLATIONS.edit-installation-location

      Event for informing changes in the installation's location

      restricted any allOf
      • #Installation

      Examples

    • #6Event for informing an update in the webserver's topologyINSTALLATIONS.installation-updated-discovery
      Message IDINSTALLATIONS.installation-updated-discovery

      Event for informing an update in the webserver's topology

      restricted any allOf
      • #Installation

      Examples

    • #7Installation's device has been moved to a different group.INSTALLATIONS.devices-moved-group
      Message IDINSTALLATIONS.devices-moved-group

      Event for informing that device has been moved to a different group.

      restricted any allOf
      • #Installation

      Examples

    • #8A new webserver has been added to an installation.INSTALLATIONS.added-ws-installation
      Message IDINSTALLATIONS.added-ws-installation

      Event for informing of a new webserver in an installation

      restricted any allOf
      • #Installation

      Examples

    • #9Installation's device current state.DEVICE_STATE
      Message IDDEVICE_STATE

      Event with information of the device state.

      restricted any allOf
      • #Installation

      Examples

    • #10Installation's device current state retrieval completed.DEVICE_STATE_END
      Message IDDEVICE_STATE_END

      Event for informing that the device status retrieval has been completed.

      restricted any allOf
      • #Installation

      Examples

    • #11User's JWT authentication request.

      Event to authenticate user in periodic authentication check.

      restricted any allOf
      • #Auth

      Examples

    • #12Webservers's updates info.WEBSERVER_UPDATES.{wsId}
      Message IDWEBSERVER_UPDATES.{wsId}

      Event with information of the webserver update changes.

      restricted any allOf
      • #Installation

      Examples

    • #13Devices's updates info.DEVICES_UPDATES.{wsId}.{deviceId}
      Message IDDEVICES_UPDATES.{wsId}.{deviceId}

      Event with information of the device state update.

      restricted any allOf
      • #Installation

      Examples

Messages

  • #1User's account deletedUSERS.delete

    Event indicating the user's account has been deleted

    Message IDUSERS.delete

    This event is fired when the user has deleted his account. This will automatically close the channel.

    restricted any allOf
    • #User
  • #2User's settings updatedUSERS.update

    Event indicating the user has updated his settings

    Message IDUSERS.update

    This event is fired upon any change the user makes in his account's settings.

    restricted any allOf
    • #User
  • #3User's completed an invitationUSERS.completed-user-invitation
    Message IDUSERS.completed-user-invitation

    Event indicating that user completed an invitation

    restricted any allOf
    • #User
  • #4User's account deletedINSTALLATIONS.user-deleted-installation
    Message IDINSTALLATIONS.user-deleted-installation

    Event for informing of user being removed from an installation

    restricted any allOf
    • #User
  • #5User's invited to an installationINSTALLATIONS.user-invited-installations
    Message IDINSTALLATIONS.user-invited-installations

    Event for informing of user being invited to a new installation

    restricted any allOf
    • #User
  • #6User's confirmed an invitation to an installationINSTALLATIONS.user-confirmed-installation
    Message IDINSTALLATIONS.user-confirmed-installation

    Event for informing of user confirmed an invitation to an installation

    restricted any allOf
    • #User
  • #7User's rejected/deleted an invitation to an installationINSTALLATIONS.user-deleted-installation-invitation
    Message IDINSTALLATIONS.user-deleted-installation-invitation

    Event for informing of rejection/deletion of an invitation to an installation

    restricted any allOf
    • #User
  • #8User's webserver has been deletedINSTALLATIONS.deleted-ws
    Message IDINSTALLATIONS.deleted-ws

    Event for informing that a webserver has been deleted.

    restricted any allOf
    • #User
  • #9User's scene has been executedINSTALLATIONS.finished-exec-scene
    Message IDINSTALLATIONS.finished-exec-scene

    Event for informing the ending of the execution of an scene

    restricted any allOf
    • #Installation
  • #10User's scene has been executedINSTALLATIONS.started-exec-scene
    Message IDINSTALLATIONS.started-exec-scene

    Event for informing the ending of the execution of an scene

    restricted any allOf
    • #Installation
  • #11User's installation permissions access has been changedINSTALLATIONS.user-edit-permission-installation
    Message IDINSTALLATIONS.user-edit-permission-installation

    Event for informing changes in the user's permission access in an installation

    restricted any allOf
    • #Installation
  • #12User's installation metaparameters has changed.INSTALLATIONS.edit-installation-meta
    Message IDINSTALLATIONS.edit-installation-meta

    Event for informing changes in the installation's metaparameters

    restricted any allOf
    • #Installation
  • #13User's installation location has changed.INSTALLATIONS.edit-installation-location
    Message IDINSTALLATIONS.edit-installation-location

    Event for informing changes in the installation's location

    restricted any allOf
    • #Installation
  • #14Event for informing an update in the webserver's topologyINSTALLATIONS.installation-updated-discovery
    Message IDINSTALLATIONS.installation-updated-discovery

    Event for informing an update in the webserver's topology

    restricted any allOf
    • #Installation
  • #15Installation's device has been moved to a different group.INSTALLATIONS.devices-moved-group
    Message IDINSTALLATIONS.devices-moved-group

    Event for informing that device has been moved to a different group.

    restricted any allOf
    • #Installation
  • #16A new webserver has been added to an installation.INSTALLATIONS.added-ws-installation
    Message IDINSTALLATIONS.added-ws-installation

    Event for informing of a new webserver in an installation

    restricted any allOf
    • #Installation
  • #17Installation's device current state.DEVICE_STATE
    Message IDDEVICE_STATE

    Event with information of the device state.

    restricted any allOf
    • #Installation
  • #18Installation's device current state retrieval completed.DEVICE_STATE_END
    Message IDDEVICE_STATE_END

    Event for informing that the device status retrieval has been completed.

    restricted any allOf
    • #Installation
  • #19Webservers's updates info.WEBSERVER_UPDATES.{wsId}
    Message IDWEBSERVER_UPDATES.{wsId}

    Event with information of the webserver update changes.

    restricted any allOf
    • #Installation
  • #20Devices's updates info.DEVICES_UPDATES.{wsId}.{deviceId}
    Message IDDEVICES_UPDATES.{wsId}.{deviceId}

    Event with information of the device state update.

    restricted any allOf
    • #Installation
  • #21User's JWT authentication request.AuthMsgReq
    Message IDAuthMsgReq

    Event to authenticate user in periodic authentication check.

    restricted any allOf
    • #Auth
  • #22User's JWT authentication response.AuthMsgResponse
    Message IDAuthMsgResponse

    Event to authenticate user in periodic authentication check.

    restricted any allOf
    • #Auth