Skip to main content

Connection

The client opens a WebSocket connection to the address below and passes the application ID and token in the query string. The server accepts the WebSocket connection right away and checks app_id and the token afterwards. The result of the check arrives as the first message, connected: with status: 1 you can send commands, with status: 2 the server closes the connection.

wss://kz1.orion-m2m.online/ws/v2/?app_id=APP_ID&token=APP_KEY
ParameterDescription
app_idApplication ID (AppID), 8 hex characters
tokenApplication token, 22 characters: Latin letters and digits. The token access level determines which commands are available and which devices are visible — see the "Access" section on each command page

The server accepts the connection if:

  • the token belongs to the application with this app_id and is not revoked;
  • the application is active;
  • the application owner's account is active;
  • the application has not reached its limit of simultaneous connections.
Current ONS version

uuid in connected is a string of 32 hex characters, not uuid64 as stated in the v0.17 description. The server does not send the die_connection_close message from the v0.17 description: a connection whose timeout has expired is closed without a message, see "Keeping the connection alive".

The connected message​

FieldTypeDescription
cmdstringconnected
statusuint81 — connection accepted, 2 — rejected
uuidstringConnection identifier, 32 hex characters. Use it to find the connection in connections_list and to close it with connection_kill. Only when status = 1
api_versionstringProtocol version, currently 0.17. Only when status = 1
clients_countuint16How many connections of the application are open, including this one. Absent on error 1
consumer_countuint16How many connections of the application are subscribed to data. The automatic subscription of this connection is not counted yet. Absent on error 1
error_code, error_textuint8, stringOnly on rejection, see below

Connection accepted:

{
    "cmd": "connected",
    "status": 1,
    "clients_count": 1,
    "consumer_count": 0,
    "uuid": "80f0769cae484a4ea7a22a023f2f6379",
    "api_version": "0.17"
}

Wrong app_id or token:

{
    "cmd": "connected",
    "status": 2,
    "error_code": 1,
    "error_text": "Auth error"
}

Errors​

error_codeerror_textWhat happened
1Auth errorapp_id or token is missing, the token does not belong to this application or is revoked, the application is disabled, or the owner account is inactive
2Clients count limit reachedThe application has the maximum number of open connections. List them with connections_list and close the extra ones

After a rejection the server sends a Close frame without a code and closes the connection. The WebSocket HTTP handshake succeeds anyway: the client learns about the rejection only from connected.

After connecting​

  1. Wait for connected with status: 1. The server ignores commands sent before that and does not reply to them. The exception is a message that cannot be parsed as JSON: the server responds to it with json_parse_error right away.
  2. If automatic subscription is enabled in the application settings, right after connected the server subscribes the connection to data and sends consume_resp without operation_id. Otherwise subscribe yourself: consume_req.
  3. Send ping_req at intervals shorter than the timeout.

Keeping the connection alive​

The server closes the connection if the client sends no ping_req for longer than the timeout. The default timeout is 300 seconds; you can change it for the current connection with set_alive_timeout.

  • Only the ping_req command resets the timer. Other commands and WebSocket protocol ping frames do not reset it.
  • The countdown starts when the connection is established.
  • The server checks the timeout every 30 seconds, so the connection is closed within 30 seconds after the timeout expires.
  • The connection is closed without a message and without a Close frame: the client sees a dropped connection, e.g. code 1006 in a browser WebSocket.

When the server closes the connection​

ReasonWhat the client sees
Rejection on connect, errors 1 and 2A connected message with status: 2, then a Close frame without a code
The timeout expired: no ping_reqA dropped connection without a message and without a Close frame
Another client closed the connection with connection_killA dropped connection without a message and without a Close frame

A data subscription lasts as long as the connection is open. While the client is disconnected, data goes to other subscribed connections of the application; if there are none, the server accumulates the data in the application queue. Reconnect and subscribe again: the accumulated data arrives as realtime_data messages.

See also​