Terra -> Your Backend

Set up and manage a consumer connection to the Terra WebSocket service to receive real-time heart rate data.

This guide will walk you through the essential steps, from connecting and authenticating to managing heartbeats and receiving data.

Setting up a Consumer Connection

Each developer ID is linked to a single data stream. To set up your consumer connection to the Terra WebSocket service, follow the steps below. For a complete Node.js example, refer to [Setting up a WebSocket Consumer].

---

Connecting to the WebSocket

Once you open a WebSocket connection to the server, you will immediately receive an Op 2 HELLO payload. This payload contains the heartbeat_interval value (in milliseconds), which the client will use to maintain the connection.

Example payload:

{
  "op": 2,
  "d": {
    "heartbeat_interval": 40000
  }
}

After receiving this payload, the client must start sending heartbeat messages, as described below.

---

Heartbeating

To keep the WebSocket connection alive, the client needs to send regular heartbeats .

This lets the server knows the connection is still active and waiting for data

To send a heartbeat, simply send the following payload in the broker:

{
  "op": 0
}

You'll always receive the following response (acknowledging your heartbeat)

{
  "op": 1
}

• The first heartbeat should be sent after heartbeat_interval * jitter milliseconds, where jitter is a random value between 0.1 and 1.0.

• After the first heartbeat, continue sending heartbeats at most at the interval specified in the HELLO payload.

• If no HEARTBEAT_ACK is received, the client should close the connection and establish a new one.

---

Authenticating the Connection

Once heartbeating is set up, the client must authenticate the connection by sending an IDENTIFY payload containing a token.

Example IDENTIFY payload:

{
  "op": 3,
  "d": {
    "token": "your_token_here",
    "type": 0
  }
}

When authentication is successful, the server will respond with an Op 4 READY message.

Example response:

{
  "op": 4
}

---

Listening for Data Updates

Once the connection is established and authenticated, the broker will start sending data through your consumer connection.

When new data is available, an Op 5 DISPATCH payload is sent, containing the relevant event data (e.g., heart rate values).

Example DISPATCH payload:

{
  "op": 5,
  "d": {
    "t": "2022-05-04T10:26:11.268507+01:00",
    "val": 95
  },
  "uid": "user_id_here",
  "seq": 73,
  "t": "HEART_RATE"
}

Each dispatch contains:

• uid: The Terra user ID.

• t: The type of event (e.g., heart rate).

• d: The actual data, including timestamps and values.

---

Requesting missed Data

WebSocket Commands

There is only one relevant command you may want to send to the broker

REPLAY Command (Op 7)

Used by consumer connections to request missed data, based on sequence numbers. This is useful when a connection drops unexpectedly.

Example REPLAY payload:

{
  "op": 7,
  "d": {
    "after": 28,
    "before": 43
  }