📄 Websocket Documentation
Anmelden

WebSocket Documentation

This document describes how to connect to and interact with our WebSocket service for receiving and managing alarm data.

1. Prerequisites

WebSocket URL: You will need the base URL for the WebSocket connection. This is typically provided during onboarding.

  • Example: wss://your-websocket-server.com:port
  • (In the current system, this is configured as wss://demo.care2graph.com:9001)

Credentials: You will need a username and password to authenticate with the service. The user associated with these credentials must be registered within the C2G (Care2Graph) system.

2. Connection

Establish a standard WebSocket connection to the provided URL. Standard WebSocket lifecycle events apply:

  • onopen: Triggered when the connection is successfully established. Authentication should be performed after this event.
  • onmessage: Triggered when a message is received from the server.
  • onerror: Triggered if a connection error occurs.
  • onclose: Triggered when the connection is closed. Implement reconnection logic as needed.

3. Authentication

Once the WebSocket connection is open, you must authenticate by sending an identification message. The user attempting to authenticate must be a registered user in the C2G system. Authentication is required before you can request data or perform actions. If authentication is not successful or not performed, the server may send an error response or close the connection.

Client Sends (LoginRequest):

{
    "type": 1,
    "operation": 0,
    "credentials": "BASE64_ENCODED_STRING"
}

Fields:

  • type: 1 (Integer) - Indicates a user identification/login message.
  • operation: 0 (Integer) - Indicates the "identify" or "login" operation.
  • credentials: (String) A Base64 encoded string constructed as described below.

credentials Field Construction by Client:

Prepare a string by concatenating the username, a client-generated salt, and a client-computed hash, separated by "@". The format is: USERNAME@SALT@CLIENT_HASH.

  • USERNAME: The user's plain username.
  • SALT: A random string generated by the client for this login attempt.
  • CLIENT_HASH: The client computes a SHA-512 hash of the user's plain-text password, using the SALT generated in the previous step. The binary output of this hash is then Base64 encoded to produce the CLIENT_HASH.

Pseudocode for CLIENT_HASH: CLIENT_HASH = Base64Encode(SHA512(SALT + PASSWORD))

The entire concatenated string (USERNAME@SALT@CLIENT_HASH) is then Base64 encoded by the client. This final Base64 string is the value for the credentials field.

Server-Side Validation:

The server decodes the credentials string, extracts the USERNAME, SALT, and CLIENT_HASH. It then retrieves the user's stored password, re-computes the hash using the provided SALT and the stored password, and compares it against the CLIENT_HASH sent by the client.

Server Responds (LoginResponse): Sent directly to the client.

{
    "type": 1,
    "operation": 0,
    "code": "<ResponseCode_Integer>",
    "reason": "<ResponseCode_String>"
}

Possible code and reason values include:

  • 200: "OK" (Successful login)
  • 201: "User already logged in."
  • 400: "Wrong password."
  • 401: "User not found."
  • 403: "Missing cryptographic functions."
  • 404: "Malformed credentials."
  • 407: "User switch forbidden."

4. General Message Format

All messages exchanged over WebSocket (both client-to-server and server-to-client) are JSON objects.

Common Message Fields:

  • type: (Integer) Defines the category of the message.
  • operation: (Integer) Defines the specific action or sub-type within the message category.

Server Response Structure (WebResponse):

Server-to-client responses generally include the following fields in addition to type and operation:

  • code: (Integer) A status code indicating the outcome of the operation (e.g., 200 for success, 4xx for client errors).
  • reason: (String) A human-readable string corresponding to the code.

Message Types:

  • TYPE_LOGIN = 1
  • TYPE_LOGOUT = 2
  • TYPE_ALARM = 3
  • TYPE_ALARMLIST = 4
  • TYPE_ERROR = 999

Operation Codes:

  • OP_NONE = 0
  • OP_CREATE = 1
  • OP_READ = 2
  • OP_UPDATE = 3
  • OP_DELETE = 4
  • OP_INCREMENT = 5
  • OP_DECREMENT = 6

Server Error Responses (ErrorResponse):

If an operation results in an error not covered by a specific response message, the server may send a generic error response directly to the originating client:

{
    "type": 999,
    "operation": "<original_operation_if_applicable>",
    "code": "<ResponseCode_Integer>",
    "reason": "<ResponseCode_String>"
}

5. API Operations

5.1. Requesting Initial Alarm List

After successful authentication, the client can request the current list of active alarms. This response is sent directly to the requesting client.

Client Sends (WebAlarmListRequest):

{
    "type": 4,
    "operation": 2
}

Server Responds (WebAlarmListResponse):

{
    "type": 4,
    "operation": 2,
    "code": 200,
    "reason": "OK",
    "alarms": [
        {
            "id": "864ac48b-a2ff-4ff6-9a3d-7d63273d0fa3",
            "type": 1,
            "location": 30,
            "deviceid": 66935,
            "devicetype": 9,
            "timestamp": 1743577927320,
            "accept": 0,
            "acceptmax": 3,
            "userid": 0,
            "message": ""
        }
    ]
}

5.2. Receiving Real-time Alarm Updates (Server-to-Client Broadcasts)

Once connected and authenticated, the server will broadcast the following real-time updates about alarms to all connected and authorized clients.

New Alarm Created (WebAlarmResponse):

When a new alarm occurs, the server broadcasts the full alarm object.

{
    "type": 3,
    "operation": 1,
    "code": 200,
    "reason": "OK",
    "alarm": { /* Full Alarm object - see section 6.1 */ }
}

Alarm Updated (WebAlarmResponse):

When an existing alarm is updated, the server broadcasts the complete, updated alarm object.

{
    "type": 3,
    "operation": 3,
    "code": 200,
    "reason": "OK",
    "alarm": { /* Full Alarm object - see section 6.1 */ }
}

Alarm Deleted / Quitted by Server (WebAlarmUUIDResponse):

When an alarm is resolved or removed from the system, the server broadcasts the ID of the deleted alarm.

{
    "type": 3,
    "operation": 4,
    "code": 200,
    "reason": "OK",
    "alarm": "alarmId-string"
}

5.3. Acknowledging / Quitting an Alarm (Client-to-Server)

To acknowledge (or "quit") an alarm.

Client Sends (WebAlarmCancellationRequest):

{
    "type": 3,
    "operation": 4,
    "cancellation": {
        "alarm": "alarmId-string",
        "message": "Reason for quitting"
    }
}

Server Response Handling:

  • On Success: The server broadcasts a WebAlarmUUIDResponse (as described in section 5.2 under "Alarm Deleted / Quitted by Server") to all connected clients.

  • On Failure: The server sends an error response directly back only to the originating client. Example:

    {
    "type": 3,
    "operation": 4,
    "code": 406,
    "reason": "Alarm not found",
    "alarm": "alarmId-string"
}

5.4. Accepting an Alarm (Client-to-Server)

To indicate that the client's user is taking responsibility for an alarm.

Client Sends (WebAlarmRequest):

{
    "type": 3,
    "operation": 5,
    "alarm": "alarmId-string"
}

Server Response Handling:

  • On Success: The server broadcasts a WebAlarmUUIDResponse to all connected clients.

    {
    "type": 3,
    "operation": 5,
    "code": 200,
    "reason": "OK",
    "alarm": "alarmId-string"
}
  • On Failure: The server sends an error response directly back only to the originating client.

5.5. Undoing Alarm Acceptance (Client-to-Server)

To revoke a previous acceptance of an alarm by the client's user.

Client Sends (WebAlarmRequest):

{
    "type": 3,
    "operation": 6,
    "alarm": "alarmId-string"
}

Server Response Handling:

  • On Success: The server broadcasts a WebAlarmUUIDResponse to all connected clients.

    {
    "type": 3,
    "operation": 6,
    "code": 200,
    "reason": "OK",
    "alarm": "alarmId-string"
}
  • On Failure: The server sends an error response directly back only to the originating client.

5.6. Client Logout

To explicitly end the authenticated session.

Client Sends:

{
    "type": 2,
    "operation": 0
}

Server Responds (LogoutResponse): Sent directly to the client.

{
    "type": 2,
    "operation": 0,
    "code": 200,
    "reason": "OK"
}

The server will clear the client's authenticated state.

6. Key Data Structures

6.1. Alarm Object (WebAlarm)

The Alarm object, as present in WebAlarmResponse and WebAlarmListResponse, has the following structure:

{
    "id": "string",
    "type": "number",
    "location": "number",
    "deviceid": "number",
    "devicetype": "number",
    "timestamp": "number",
    "accept": "number",
    "acceptmax": "number",
    "userid": "number",
    "message": "string"
}

Contextual Data Resolution:

Fields like type (alarm category), location, deviceid, and devicetype are numerical IDs. The client application would typically resolve these IDs against other data sources to display human-readable information.