> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/streaming-api/websocket-reference.md).

# WebSocket protocol

The WebSocket handshake, payload format, opcodes, data types and close codes for the Streaming API.

This page describes the WebSocket protocol that producers and consumers speak with Terra. The RT SDKs handle it for you; read it if you connect without an SDK.

## Identify data schema

<table><thead><tr><th width="133">Field name</th><th width="95">Type</th><th>Description</th></tr></thead><tbody><tr><td>token</td><td>String</td><td>Authentication token generated from the <a href="/reference/streaming-api/api-endpoints.md">appropriate endpoint</a> for your connection type: <code>/auth/user</code> for a producer (type 0), <code>/auth/developer</code> for a consumer (type 1).</td></tr><tr><td><a href="#identify-type-enum">type</a></td><td>Integer</td><td>Connection type. Value from the IdentifyType enum.</td></tr></tbody></table>

## Identify type enum

<table><thead><tr><th width="236">Name</th><th>Value</th></tr></thead><tbody><tr><td>User (Producer)</td><td>0</td></tr><tr><td>Developer (Consumer)</td><td>1</td></tr></tbody></table>

## Payload format

<table><thead><tr><th width="140">Field name</th><th width="112">Type</th><th>Description</th></tr></thead><tbody><tr><td>op</td><td>Integer</td><td><a href="#opcodes">Opcode</a> for the payload.</td></tr><tr><td>d?</td><td>Object</td><td>Event data.</td></tr><tr><td>uid?*</td><td>String</td><td>User ID that the event relates to.</td></tr><tr><td>seq?*</td><td>Long</td><td>Sequence number of the payload. Used when replaying missed payloads.</td></tr><tr><td>t?*</td><td>String</td><td>The <a href="#data-types">data type</a> of the payload.</td></tr></tbody></table>

{% hint style="info" %}
`?` marks an optional field.\
`*` marks a field sent only with [`DISPATCH`](#opcodes) payloads.
{% endhint %}

### Example payload

{% tabs %}
{% tab title="Dispatch Payload" %}

```json
{
  "op": 5,
  "d": {
    "ts": "2022-05-04T10:26:11.268507+01:00",
	"val": 95
	},
  "uid": "8e864e3a-979a-4d04-b4e9-b6d020f20ba0",
  "seq": 73,
  "t": "HEART_RATE"
}
```

{% endtab %}

{% tab title="Client Payload" %}

```json
{
  "op": 6,
  "d": {
        "val": 95
	},
  "t": "HEART_RATE"
}
```

{% endtab %}

{% tab title="Heartbeat" %}
When you open a WebSocket connection, the server immediately sends an `Op 2 HELLO` payload. It contains the heartbeat interval, in milliseconds, at which the client must send `HEARTBEAT` payloads.

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

The server answers each heartbeat with a `HEARTBEAT_ACK`:

```json
{"op": 1} // Sent back to the client by the server every "heartbeat_interval" ms
```

{% endtab %}
{% endtabs %}

## Opcodes

<table><thead><tr><th width="199">Name</th><th width="50">Value</th><th width="287">Description</th><th>Sent by</th></tr></thead><tbody><tr><td>HEARTBEAT</td><td>0</td><td>Fired periodically by the client to keep the connection alive.</td><td>Client</td></tr><tr><td>HEARTBEAT_ACK</td><td>1</td><td>Sent by the server to acknowledge that a heartbeat has been received.</td><td>Server</td></tr><tr><td>HELLO</td><td>2</td><td>Sent by the server immediately after connecting. Contains the heartbeat interval for the client to use.</td><td>Server</td></tr><tr><td>IDENTIFY</td><td>3</td><td>Sent by the client to complete the handshake with the server. Contains authentication details.</td><td>Client</td></tr><tr><td>READY</td><td>4</td><td>Sent by the server once the handshake has been completed. The client can send and receive payloads as soon as it arrives.</td><td>Server</td></tr><tr><td>DISPATCH</td><td>5</td><td>An event dispatched by the server. Contains details about the event, as well as the data payload for the event.</td><td>Server</td></tr><tr><td>SUBMIT</td><td>6</td><td>Sent by the client to submit data, which the server routes to the developer's consumers.</td><td>Client (producer only)</td></tr><tr><td>REPLAY</td><td>7</td><td>Request a replay of payloads between a lower (<code>after</code>) and upper (<code>before</code>) sequence bound. Both bounds are required and exclusive.</td><td>Client (consumer only)</td></tr></tbody></table>

## Data types

<table><thead><tr><th width="207">Name</th><th>Description</th></tr></thead><tbody><tr><td>HEART_RATE</td><td><code>val</code> is the BPM of each reading</td></tr><tr><td>STEPS</td><td><code>val</code> the amount of accumulated steps</td></tr><tr><td>DISTANCE</td><td><code>val</code> the accumulated distance in meters</td></tr><tr><td>FLOORS_CLIMBED</td><td><code>val</code> the accumulated floors climbed</td></tr><tr><td>STEPS_CADENCE</td><td><code>val</code> the amount of steps per second taken by the user</td></tr><tr><td>SPEED</td><td><code>val</code> the speed in meter per second of the user</td></tr><tr><td>ACCELERATION</td><td><code>d</code> the acceleration data of the device.<br>- <code>d[0]</code> -> acceleration in x direction<br>- <code>d[1]</code> -> acceleration in y direction<br>- <code>d[2]</code> -> acceleration in z direction</td></tr><tr><td>GYROSCOPE</td><td><code>d</code> the rotation rate of the device.<br>- <code>d[0]</code> -> rotation in x direction<br>- <code>d[1]</code> -> rotation in y direction<br>- <code>d[2]</code> -> rotation in z direction</td></tr></tbody></table>

## Close codes

<table><thead><tr><th width="113">Code</th><th>Reason</th></tr></thead><tbody><tr><td>1000</td><td>Normal closure (including server shutdown)</td></tr><tr><td>1003</td><td>A malformed frame was received (unparseable JSON)</td></tr><tr><td>1011</td><td>Internal server error</td></tr><tr><td>4000</td><td>IDENTIFY payload expected but was not received</td></tr><tr><td>4001</td><td>Improper or expired token was passed for IDENTIFY</td></tr><tr><td>4002</td><td>Consumer session limit reached for this developer ID</td></tr><tr><td>4003</td><td>Multiple IDENTIFY payloads received</td></tr><tr><td>4004</td><td>Unrecognised opcode, or an opcode not valid for this session type (e.g. SUBMIT on a consumer, REPLAY on a producer)</td></tr><tr><td>4005</td><td>Heartbeat expected but was not received</td></tr></tbody></table>
