Terra -> Your backend

Set up and manage a consumer connection to the Terra WebSocket service to receive real-time health 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.

WebSocket endpoint: wss://ws.tryterra.co/connect

---

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 know the connection is still active and waiting for data.

To send a heartbeat, send the following payload:

{
  "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 and 1.

• 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.

• If the server does not receive a heartbeat within the heartbeat_interval window, it will close the connection with code 4005.

---

Authenticating the Connection

You must send an IDENTIFY payload within 15 seconds of connecting. If the server does not receive IDENTIFY in time, it will close the connection with code 4000.

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

IDENTIFY payload:

{
  "op": 3,
  "d": {
    "token": "your_developer_token_here",
    "type": 1
  }
}

The type field specifies the connection type:

Type	Name	Description
0	USER	Producer connection (mobile SDKs sending data). Uses a token from POST /auth/user.
1	DEVELOPER	Consumer connection (your backend receiving data). Uses a token from POST /auth/developer.

For consumer connections (this guide), use type: 1 with a developer token.

Tokens are single-use. Each token is deleted from the server after a successful IDENTIFY. If your connection drops, you must generate a new token before reconnecting.

One connection per developer. Only one active consumer connection is allowed per developer ID. If you attempt to connect while a previous session is still active, the new connection will be closed with code 4002. Close the previous connection first.

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

{
  "op": 4
}

---

Listening for Data Updates

Once the connection is established and authenticated, data from your connected users will be streamed to you in real time.

When new data is available, an Op 5 DISPATCH payload is sent:

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

Each dispatch contains:

• op: Opcode 5 (DISPATCH).

• uid: The Terra user ID of the user whose device produced this data.

• t: The data type (e.g., "HEART_RATE", "STEPS", "ACCELERATION", "ECG", "HRV", "CALORIES", "LOCATION", "GYROSCOPE", etc.).

• seq: Monotonically increasing sequence number per developer. Used for ordering and replay.

• d: The data payload:

  • ts: ISO 8601 timestamp of the reading.

  • val: Scalar value (e.g., heart rate BPM, step count). Present for single-value types.

  • d: Array of doubles (e.g., [x, y, z] for accelerometer/gyroscope, or [lat, lng] for location). Present for multi-axis types.

---

Requesting missed Data

If your connection drops and you miss some data, you can request it using the REPLAY command once you reconnect.

REPLAY Command (Op 7)

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

• after (required): Replay messages with sequence numbers greater than this value.

• before (optional): Replay messages with sequence numbers less than this value. Omit to replay everything after after.

Bounds are exclusive — after: 28, before: 43 replays sequence numbers 29 through 42.

Replayed messages arrive as standard DISPATCH (op 5) payloads.

2-day replay window. Data payloads older than 2 days are purged from the server. REPLAY only works for data within this window.

---

Error Close Codes

The server may close your WebSocket connection with one of the following custom close codes:

Code	Reason	What to do
4000	Identify expected but was not received	Send IDENTIFY within 15 seconds of connecting
4001	Improper token has been passed	Token is invalid or expired — generate a new one
4002	Duplicate connection	Another session is already active for your developer ID — close it first
4003	Multiple IDENTIFY payloads received	Don't send IDENTIFY more than once per connection
4004	Invalid opcode was received	You sent an opcode the server doesn't recognize for your connection type
4005	Heartbeat expected but was not received	Send heartbeats within the heartbeat_interval window

---

Opcode Reference

Opcode	Name	Direction	Description
0	HEARTBEAT	Client → Server	Keep-alive ping
1	HEARTBEAT_ACK	Server → Client	Keep-alive acknowledgement
2	HELLO	Server → Client	Sent on connection, contains heartbeat_interval
3	IDENTIFY	Client → Server	Authentication with token and connection type
4	READY	Server → Client	Authentication successful
5	DISPATCH	Server → Client	Real-time data payload
6	SUBMIT	Client → Server	Data submission (producer connections only)
7	REPLAY	Client → Server	Request missed data by sequence range