Skip to main content

Keeping the connection alive: ping_req

Tells the server the client is still there. If the client sends no ping_req for longer than the timeout — 300 seconds by default — the server closes the connection. Only ping_req resets the timer: other commands and WebSocket protocol ping frames do not, so ping_req is needed even if the client is actively sending requests.

Request and response: ping_req → ping_resp.
Access: a token of any access level.

Current ONS version

operation_id is not returned in the response. The seq counter starts at 1 and goes up to 65536, then starts at 1 again; the v0.17 description gives the range 0–65535.

Request​

Fields not marked as required may be omitted.

FieldTypeDescription
cmdstringping_req
operation_idstringMay be passed, but the server does not return it in the response
{
    "cmd": "ping_req"
}

Response​

FieldTypeDescription
cmdstringping_resp
sequint32Number of the ping_req in this connection: 1, 2, 3… After 65536 the count starts at 1. In a new connection the count starts over
{
    "cmd": "ping_resp",
    "seq": 42
}

Errors​

The command returns no errors: after connected the server always responds with ping_resp.

Good to know​

  • Send it more often than the timeout. The server checks the timeout every 30 seconds and closes the connection at the first check after it expires. With a 300-second timeout, one ping_req per minute is enough.
  • The countdown starts on connect. The first ping_req is due within the timeout after the connected message.
  • Closing on timeout comes without warning. The server sends no message and no Close frame: the client sees a dropped connection, e.g. code 1006 in a browser WebSocket. The data subscription is removed — subscribe again after reconnecting.
  • The command does not work before connected. The server skips requests sent before the connection is confirmed and sends no reply.

See also​