# Websocket

## Introduction

`WebSocket` is the alternate transport to getting data from the server. The process of notification about events occurs\
from the server to the client through a constantly open connection. This allows you to display changes in real time.

Currently, the [Atmosphere Framework](https://github.com/Atmosphere) used as an application layer library and protocol.

## Standard workflow

Let's describe a standard workflow for WebSocket API:

1. Determine [API base URL](/docs/navixy-api/user-api/backend-api.md#api-base-url).
2. Get the hash of an [API Key](/docs/navixy-api/user-api/backend-api/resources/commons/api-keys.md).
3. Open WebSocket connection by the path [/event/subscription/](/docs/navixy-api/user-api/backend-api/websocket/subscription.md) with `Atmosphere` protocol parameters.
4. Subscribe on events using [subscribe action](/docs/navixy-api/user-api/backend-api/websocket/subscription.md#subscribe-action).
5. Listen and process the [incoming events](/docs/navixy-api/user-api/backend-api/websocket/events.md).
6. Subscribe and unsubscribe on the events if needed.
7. Unsubscribe when leaving monitoring page using [unsubscribe action](/docs/navixy-api/user-api/backend-api/websocket/subscription.md#unsubscribe-action).

> **Notes:**
>
> * The [subscription requests](/docs/navixy-api/user-api/backend-api/websocket/subscription.md) must contain the `hash` of an [API Key](/docs/navixy-api/user-api/backend-api/resources/commons/api-keys.md).
> * Responses and errors for [subscribe](/docs/navixy-api/user-api/backend-api/websocket/subscription.md#subscribe-action) and [unsubscribe](/docs/navixy-api/user-api/backend-api/websocket/subscription.md#unsubscribe-action) actions are similar with common [API](/docs/navixy-api/user-api/backend-api.md) format.
> * All `WebSocket` frames use a `JSON` format. Exceptions are heartbeat frames containing "X".

## Open connection

In a simplified form, opening the WebSocket using [atmosphere-javascript](https://github.com/Atmosphere/atmosphere-javascript) looks like this:

```js
  var subSocket;
  
  function sendSubsrcibeRequest() {
      console.log('sending subsrcibe action to websocket');
      subSocket.push(JSON.stringify({
          action: 'subscribe',
          hash: 'e4c24xxx4a08e9xxxc337xxxx5ca04e1',
          requests: [
              {
                  type: 'state_batch',
                  target: {
                      type: 'all'
                  }
              },
              {
                  type: 'readings_batch',
                  target: {
                      type: 'all'
                  }
              }
          ]
      }));
  }
  
  var request = {
      url: 'https://api.eu.navixy.com/v2/event/subscription',
      contentType : "application/json",
      logLevel : 'debug',
      transport : 'websocket',
      trackMessageLength : false,
      reconnectInterval: 2000,
      onOpen: function(r) {
          console.log('onOpen', r);
          sendSubsrcibeRequest();
      },
      onReopen: function(r) {
          console.log('onReopen', r);
          sendSubsrcibeRequest();
      },
      onMessage: function (msg) {
          console.log('onMessage', msg);
      },
      onClientTimeout: function(r) {
          console.log('onClientTimeout', r);
      },
      onTransportFailure: function(errorMsg, request) {
          console.log('onTransportFailure', errorMsg);
      },
      onClose: function(r) {
          console.log('onClose', r);
      },
      onError: function(r) {
          console.log('onError', r);
      },
      onReconnect: function(request, response) {
          console.log('onReconnect', response);
      }
  };
  
  subSocket = atmosphere.subscribe(request);
```

Executing this code will lead to send a request

{% code overflow="wrap" %}

```
wss://domain.com/event/subscription?X-Atmosphere-tracking-id=0&X-Atmosphere-Framework=2.3.6-javascript&X-Atmosphere-Transport=websocket&Content-Type=application/json&X-atmo-protocol=true
```

{% endcode %}

and upgrade the connection to the WebSocket.\
After that, will be sent a first frame through the opened WebSocket channel:

```
b623a15d-9623-4fd8-a9d3-697036635c29|30000|X|
```

This is service message for the Atmosphere protocol negotiation.\
Now everything is ready to [subscribe on events](/docs/navixy-api/user-api/backend-api/websocket/subscription.md#subscribe-action).

## Common fields

All messages from client side contain field `action` with action name (e.g. "subscribe" or "unsubscribe").

All messages from server side contain field `type` with message type ("event", "response" or "error") and `data` with a payload.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://navixy.com/docs/navixy-api/user-api/backend-api/websocket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.