WebSocket Subscription¶

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

Subscribe Action¶

Request¶

Request parameters:

• action (text: "subscribe").
• hash - required. Hash of an API Key action.
• trackers - required, int array, without nulls. List of tracker ids for the events that require a subscription.
• events - required, enum array, 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, array of enum, without nulls. List of the subscribed events. Event can be state.
• data - required, map . Map with events subscription result. One key per subscribed event.
• state - presented 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. State events for this tracker will be delivered to client.
• blocked - tracker blocked. State events for this tracker will not be delivered to client.

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

• unknown - tracker id missed in the database or not belong to current user.
• disallowed - subscription for this tracker not allowed by the 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 made. When changing the state of any tracker to which a subscription made, the server will send a new state in the event message.

Automatic subscriptions¶

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

Unsubscribe Action¶

Request¶

Request parameters:

• action - text: "unsubscribe".
• hash - required. Hash of an API Key action.
• trackers - required, int array, without nulls. List of tracker ids for events that require an unsubscription.
• events - required, enum array, without nulls. List of events to unsubscribe. Event can be 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 array, without nulls. List of unsubscribed events. Event can be state.
• data - required, int array, without nulls. List of 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 hash"
    },
    "data": {
        "events": ["state"],
        "trackers": [15564]
    }
}