WebSocket Subscription

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 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"
     }
   }
}

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.

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

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 a 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 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]
}

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]
   }
}