Skip to content

Saveris Push API V1.0

Click on the following link to open the Push API.

The Push API is a WebSocket-based service that allows users to subscribe to alarm messages. These messages are buffered in a queue when users are disconnected from the server and are retrieved once reconnection occurs.

This documentation will guide you on how to use this API and subscribe to the alarm messages.

API Details

  • AsyncAPI Version: 2.6.0
  • API Version: 1.0
  • License: Apache 2.0

Server URL

The URL for this service is: wss://tds-real-time-api.REGION.ENV.savr.saveris.net/web-socket

The REGION and ENV in the URL should be replaced with the specific region and environment you are using. There are two environments available: "i" for integration and testing, and "p" for production. Furthermore we have three regions: "eu" for europe, "am" for america and "ap" for the apac region.

Security

The Push API uses Bearer token authentication. You should acquire a token and use it to authenticate your requests.

To get a token you need to authenticate using a token endpoint. Follow these steps to authenticate and obtain an ID token:

  1. Send a POST request to https://cognito-idp.eu-central-1.amazonaws.com/ with headers:
  2. X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
  3. Content-Type: application/x-amz-json-1.1
  4. Request body: 
    {
   "AuthParameters" : {
      "USERNAME" : "example-user",
      "PASSWORD" : "your-password"
   },
   "AuthFlow" : "USER_PASSWORD_AUTH",
   "ClientId" : "your-client-id"
}
  5. The response will contain a JSON object with an IdToken field. This token is valid for 24 hours and must be used for authentication in the following steps.

Another Approach is to get the token from the /token endpoint of the Data API. Here you will just need to send your username and password in the body and you will receive the idToken. The documentation for the Data API is to be found here: Data API

Subscription

You can subscribe to the alarm messages by subscribing to the channel /queue/<username>/alarms. The username should be replaced with the username you used while acquiring the token.

Here is a sample code in JavaScript showing how to subscribe to the alarm channel:

import {RxStomp, StompHeaders} from "@stomp/rx-stomp";
import { WebSocket } from 'ws';

Object.assign(global, { WebSocket});

const token = ""; // replace with your token

const rxStomp = new RxStomp();

rxStomp.configure({
    brokerURL: 'wss://tds-real-time-api.eu.i.savr.saveris.net/web-socket',
    debug: console.log.bind(console),
    connectHeaders: {Authorization: `Bearer ${token}`}
});

rxStomp.activate();

let subHeaders = new StompHeaders();

const subscription = rxStomp.watch({ 
    destination: "/queue/<username>/alarms", 
    subHeaders 
}).subscribe((message) => {console.log(message.body)});

Messages

The API provides two types of alarm events:

  1. Measurement Alarm: This event type provides information about a specific measurement alarm. The content type of the message is application/json.

  2. System Alarm: This event type provides information about a device/sensor system alarm. The content type of the message is application/json.

Each event type carries a payload of alarm information, including details such as the unique identifier of the alarm, tenant, alarm reason, status, condition type, severity, alarm time, and more.

Please refer to the API's AsyncAPI document for the detailed structure of the alarm messages.