WebSocket Subscription¶

The subscribe and unsubscribe actions are used by client-side to subscribe on server events and unsubscribe from them. This actions are similar with any other API REST actions, but must be sending inside an open WebSocket channel and use only JSON format for the messages between client and server.

Subscribe Action¶

Request¶

Request parameters:

• action (text: "subscribe").
• hash (required, string, length=32): session hash code gotten by user/auth action.
• trackers (required, int[], without nulls) - list of tracker ids for the events that require a subscription.
• events (required, enum[], without nulls) - list of events to subscribe. Event can be one of: state.

Request sample:

{
  "action": "subscribe",
  "hash": "f4bf1b75403d851653dad99c78c4b237",
  "events": ["state"],
  "trackers": [15564, 15565, 15568]
}

Response¶

Response parameters:

• type (required, text: "response").
• action (required, text: "subscription/subscribe").
• events (required, enum[], without nulls) - list of the subscribed events. Event can be one of: state.
• data (required, map, without nulls) - map with the events subscription result. One key on each subscribed event.
• state (presents if the "state" subscription requested, map) - the current status of requested trackers.

Keys is a tracker ids, values - one of the item:

• normal - non-blocked, normal status. The state events for this tracker will be delivered to client.
• blocked - tracker is blocked. The state events for this tracker will not be delivered to client.

The lifecycle events will be delivered. After unblocking, current tracker state will be sent automatically.

• unknown - tracker id is missed in database or not belong to current user.
• disallowed - subscription for this tracker is not allowed by current session.

Response sample:

{
  "type": "response",
  "action": "subscription/subscribe",
  "events": ["state"],
  "data": {
    "state": {
      "15564": "normal",
      "15565": "blocked",
      "15568": "unknown"
    }
  }
}

The "state" event subscription¶

After subscribe on the "state", server will send the current states of all non-blocked trackers to which the subscription was made. When changing the state of any tracker to which a subscription is made, the server will send a new state in event message.

Automatic subscriptions¶

• Subscribing to a state automatically creates a subscription to the lifecycle events.
• Subscribing to any event automatically creates a subscription to the logout events.

Unsubscribe Action¶

Request¶

Request parameters:

• action (text: "unsubscribe").
• hash (required, string, length=32): session hash code gotten by user/auth action.
• trackers (required, int[], without nulls) - list of tracker ids for the events that require an unsubscription.
• events (required, enum[], without nulls) - list of events to unsubscribe. Event can be one of: state.

Request sample:

{
  "action": "unsubscribe",
  "hash": "f4bf1b75403d851653dad99c78c4b237",
  "events": ["state"],
  "trackers": [15568]
}

Response¶

Response parameters:

• type (required, text: "response").
• action (required, text: "subscription/unsubscribe").
• events (required, enum[], without nulls) - list of the unsubscribed events. Event can be one of: state.
• data (required, int[], without nulls) - list of the tracker ids from request.

Response sample:

{
  "type": "response",
  "action": "subscription/unsubscribe",
  "events": ["state"],
  "data": [15568]
}

Error Response¶

If something goes wrong, the server may respond with an error. Error codes are similar to the API errors codes.

Error response parameters:

• type (required, text: "error").
• action (required, string) - action from request (e.g. "subscription/subscribe") or "null" for some unexpected errors.
• status (required) - error code and description:
• code (required) - error code (see API errors codes).
• description (required, string) - error description.
• data (optional, string) - part of parameters from request or some info for unexpected errors.

Error response sample:

{
    "type": "error",
    "action": "subscription/subscribe",
    "status": {
        "code": 3,
        "description": "Wrong user hash"
    },
    "data": {
        "events": ["state"],
        "trackers": [15564]
    }
}