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
Airzone's Cloud Websocket API allows the subscription to user related events and installation related 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/userWhen 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:
Installation namespace:
The following image describes the intented use of the websocket API:
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:
Webserver's changes namespace:
Device's changes namespace:
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.
The following image describes the intented use of the websocket API:
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).
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:
In such cases, server will append to close event a 4001
status code and a description message.
The following image describes the intented use of the websocket API:
In case of needing to listen to multiple sites at the same time, one independent websocket connection per each site should be established.
Below are two example codes by which a websocket client can listen to airzone user events and installation 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}`);
});
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.
Production server
Channel where user events are published.
Available only on servers:
Accepts the following message:
Event to authenticate user in periodic authentication check.
{
"corrId": "d4edbe80-a3b5-4942-87fd-f341098ccf89",
"body": {
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJGTXdydVEyN29Ldkt1S1Zy bWlhS1pHaGhhd09GTnNOTCIsInRva2VuSWQiOiI1OWYyODQ5Yy02MDMyLTQwYTItYjc0O C04OGE0OTljN2UwMGMiLCJzY29wZXMiOnsiYXoiOiI2MjE3N2NhYmE4Y2RiZDIxN2I1MD hmNDcifSwianRpIjoiMGM5NDk4MGEtYzdjZC00YjA3LWI2M2MtMWNkODg0NmE3N2QxIiw iaWF0IjoxNjk1MDUxMTI2LCJleHAiOjE2OTUyMjM5MjZ9.r0-FMqVm_xmy7AkeRbyLP0B vPC4nTR4IAVA57fDoowQ"
}
}
Channel where user events are published.
Available only on servers:
Accepts one of the following messages:
Event indicating the user has updated his settings
This event is fired upon any change the user makes in his account's settings.
{
"event": "USERS.completed-user-invitation",
"body": {
"param": "lang",
"value": "string"
}
}
Event indicating the user's account has been deleted
This event is fired when the user has deleted his account. This will automatically close the channel.
{
"event": "USERS.completed-user-invitation",
"body": {
"user_id": "5dd28d9e46aea00329682378"
}
}
Event indicating that user completed an invitation
{
"event": "USERS.completed-user-invitation",
"body": {
"user_id": "5dd28d9e46aea00329682378",
"name": "Edu"
}
}
Event for informing of user being removed from an installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380"
}
}
Event for informing of user being invited to a new installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"user_id": "5dd28d9e46aea00329682378"
}
}
Event for informing of user confirmed an invitation to an installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"user_id": "5dd28d9e46aea00329682378"
}
}
Event for informing of rejection/deletion of an invitation to an installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"user_id": "5dd28d9e46aea00329682378"
}
}
Event to authenticate user in periodic authentication check.
{
"event": "auth",
"corrId": "d4edbe80-a3b5-4942-87fd-f341098ccf89",
"args": [
[
"authenticate"
]
]
}
Channel where related installations events are published.
Available only on servers:
site's installation_id
Accepts the following message:
Event to authenticate user in periodic authentication check.
{
"corrId": "d4edbe80-a3b5-4942-87fd-f341098ccf89",
"body": {
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJGTXdydVEyN29Ldkt1S1Zy bWlhS1pHaGhhd09GTnNOTCIsInRva2VuSWQiOiI1OWYyODQ5Yy02MDMyLTQwYTItYjc0O C04OGE0OTljN2UwMGMiLCJzY29wZXMiOnsiYXoiOiI2MjE3N2NhYmE4Y2RiZDIxN2I1MD hmNDcifSwianRpIjoiMGM5NDk4MGEtYzdjZC00YjA3LWI2M2MtMWNkODg0NmE3N2QxIiw iaWF0IjoxNjk1MDUxMTI2LCJleHAiOjE2OTUyMjM5MjZ9.r0-FMqVm_xmy7AkeRbyLP0B vPC4nTR4IAVA57fDoowQ"
}
}
Channel where related installations events are published.
Available only on servers:
site's installation_id
Accepts one of the following messages:
Event for informing that a webserver has been deleted.
{
"event": "USERS.completed-user-invitation",
"body": {
"ws_id": "string",
"installation_id": "5dd28d9e46aea00329682380",
"devices_ids": [
"string"
]
}
}
Event for informing the ending of the execution of an scene
{
"event": "USERS.completed-user-invitation",
"body": {
"scene_id": "string"
}
}
Event for informing the ending of the execution of an scene
{
"event": "USERS.completed-user-invitation",
"body": {
"scene_id": "string"
}
}
Event for informing changes in the user's permission access in an installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"user_id": "5dd28d9e46aea00329682378",
"access_type": "basic",
"groups": [
{
"group_id": "5dd28d9e46aea00329682371",
"name": "Planta baja",
"icon": 0,
"devices": [
{
"device_id": "5dd28d9e46aea00329682378",
"name": "Salón",
"icon": 2,
"type": "az_zone",
"ws_id": "AA:BB:CC:DD:EE:FF"
}
]
}
]
}
}
Event for informing changes in the installation's metaparameters
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"change": {
"name": "Casa"
}
}
}
Event for informing changes in the installation's location
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"location": {
"_id": "5dd28d9e46aea00329682370",
"google_place_id": "ChIJpbwTNaZ5lVQRrZW-t-PxZiE",
"timezoneId": "Europe/Madrid",
"coords": {
"lat": 45.54,
"lng": 3.45
},
"text": {
"city": {
"es": "Málaga"
},
"country": {
"es": "España"
}
}
}
}
}
Event for informing an update in the webserver's topology
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"wsId": "string"
}
}
Event for informing that device has been moved to a different group.
{
"event": "USERS.completed-user-invitation",
"body": {
"device_id": "string",
"installation_id": "5dd28d9e46aea00329682380"
}
}
Event for informing of a new webserver in an installation
{
"event": "USERS.completed-user-invitation",
"body": {
"installation_id": "5dd28d9e46aea00329682380",
"wsId": "string"
}
}
Event with information of the device state.
{
"event": "USERS.completed-user-invitation",
"body": {
"device_id": "64953973418c8b8aa228f6e8",
"device_type": "aidoo_it",
"ws_id": "AA:BB:CC:DD:EE:FF",
"status": {
"humidity": 23,
"block_mode": false,
"block_off": false,
"block_on": false,
"block_autospeed": false,
"block_autotemp": false,
"block_dryspeed": false,
"block_drytemp": false,
"block_fantemp": true,
"block_setpoint": false,
"manufacturer": {
"_id": 2,
"text": "Mitsubishi Electric"
},
"aidooit": false,
"machineready": false,
"isConnected": true,
"power": true,
"mode": 1,
"mode_available": [
0,
1,
2,
3,
4
],
"auto_mode": 2,
"speed_values": [
0,
1,
2,
3
],
"speed_type": 0,
"step": {
"fah": 0,
"celsius": 0
},
"range_sp_cool_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_cool_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_hot_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_hot_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_dry_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_dry_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_vent_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_vent_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_emerheat_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_emerheat_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_auto_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_auto_air_max": {
"fah": 68,
"celsius": 25
},
"range_sp_stop_air_min": {
"fah": 68,
"celsius": 25
},
"range_sp_stop_air_max": {
"fah": 68,
"celsius": 25
},
"setpoint_air_heat": {
"fah": 68,
"celsius": 25
},
"setpoint_air_emerheat": {
"fah": 68,
"celsius": 25
},
"setpoint_air_cool": {
"fah": 68,
"celsius": 25
},
"setpoint_air_vent": {
"fah": 68,
"celsius": 25
},
"setpoint_air_dry": {
"fah": 68,
"celsius": 25
},
"setpoint_air_auto": {
"fah": 68,
"celsius": 25
},
"setpoint_air_stop": {
"fah": 68,
"celsius": 25
},
"double_sp": true,
"local_temp": {
"fah": 68,
"celsius": 25
},
"speed_conf": 0,
"eco_conf": "off",
"eco_values": [
"off",
"manual",
"a",
"a_p",
"a_pp"
],
"usermode_conf": "comfort",
"usermode_values": [
"stop",
"comfort",
"unoccupied",
"night",
"eco",
"vacation"
],
"aq_mode_conf": "off",
"aq_mode_values": [
"off",
"on",
"auto"
],
"warnings": [
{
"_id": "window"
}
],
"errors": [
{
"_id": "trv_mainboard_missing"
}
],
"aqpm1_0": 23,
"aqpm2_0": 3,
"aqpm10": 10,
"aq_quality": "bad"
}
}
}
Event for informing that the device status retrieval has been completed.
{
"event": "USERS.completed-user-invitation",
"body": {
"installationId": "64953973418c8b8aa228f6e8"
}
}
Event to authenticate user in periodic authentication check.
{
"event": "auth",
"corrId": "d4edbe80-a3b5-4942-87fd-f341098ccf89",
"args": [
[
"authenticate"
]
]
}
Event with information of the webserver update changes.
{
"event": "USERS.completed-user-invitation",
"body": {
"ws_id": "string",
"change": {}
}
}
Event with information of the device state update.
{
"event": "USERS.completed-user-invitation",
"body": {
"ws_id": "string",
"change": {}
}
}
Event indicating the user's account has been deleted
This event is fired when the user has deleted his account. This will automatically close the channel.
Event indicating the user has updated his settings
This event is fired upon any change the user makes in his account's settings.
Event indicating that user completed an invitation
Event for informing of user being removed from an installation
Event for informing of user being invited to a new installation
Event for informing of user confirmed an invitation to an installation
Event for informing of rejection/deletion of an invitation to an installation
Event for informing that a webserver has been deleted.
Event for informing the ending of the execution of an scene
Event for informing the ending of the execution of an scene
Event for informing changes in the user's permission access in an installation
Event for informing changes in the installation's metaparameters
Event for informing changes in the installation's location
Event for informing an update in the webserver's topology
Event for informing that device has been moved to a different group.
Event for informing of a new webserver in an installation
Event with information of the device state.
Event for informing that the device status retrieval has been completed.
Event with information of the webserver update changes.
Event with information of the device state update.
Event to authenticate user in periodic authentication check.
Event to authenticate user in periodic authentication check.