Heartbeats

As part of the keep-alive strategy for Doshii WebSocket connections, it is necessary to be capable of sending and receiving heartbeats on an established WebSocket connection.

Initiated by Client

As described in the article, Use of WebSockets, it is necessary to periodically send a heartbeat (ping) to Doshii to help maintain the connection and ensure Doshii does not treat the connection as inactive. The recommended interval is every 30 seconds.

The ping event should be of the form:

{
    "doshii": {
        "ping": <unix time in milliseconds>,
        "version": "<pos version>"
    }
}

e.g.

{
    "doshii": {
        "ping": 1539144663417,
        "version": "5.3.72"
    }
}

An example, using NodeJS for the ping event:

ws.on('open', function(event) {
  function heartbeat() {
    const timestamp = Date.now();
    const posVersion = '5.3.72';
    const payload = JSON.stringify({
        doshii: {
            ping: timestamp,
            version: posVersion
        }
    });
    ws.send(payload);
  }

  heartbeat(); // Send one immediately to complete the handshake
  setInterval(heartbeat, 30000); // Then 30 every seconds or so thereafter to keep alive
});

The ping event also supports an optional status property that can contain one or many properties to indicate the current health of the POS:

{
    "doshii": {
        "ping": 1539144663417,
        "version": "5.3.72",
        "status": {
            "database": "online",
            "processor": "offline"
        }
    }
}

In response to the ping event, Doshii will respond with a pong event. Responding with the unix time in milliseconds that was supplied in the original ping, along with the current API version.

{
    "type": "message",
    "data": { "doshii": { "pong": 1539153237588, "version": "3.2.0" } }
}

Initiated by Doshii (Health Check)

Similar to the heartbeat logic described above, Doshii will also periodically send its own "ping" message on the established connection, in the form of a health_check event, expecting to receive a pong as a response.

EVENT health_check

{
    "type": "health_check",
    "data": {
        "ping": 1539153237588
    }
}

In response to the health check event, it is expected that your POS system will respond with a "pong" in the same format that the standard heartbeat uses, including the POS version and any status information. Responding with the unix time in milliseconds that was supplied in the original ping.

{
    "doshii": {
        "pong": event.ping,
        "version": "5.7.13",
        "status": {
            "database": "online",
            "processor": "online"
        }
    }
}