# Websocket Reference

## 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="/pages/2oGKJhw2wdhuHBpXXgcw">appropriate endpoint.</a></td></tr><tr><td><a href="#identifytype-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> for the payload.</td></tr></tbody></table>

{% hint style="info" %}
`? -> Optional field`\
`* -> Only send with payloads of the`[`DISPATCH`](#opcodes)`opcode`
{% 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" %}

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

{% endtab %}

{% tab title="Heartbeat" %}
**Heartbeat**

Upon opening a websocket connection to the server, you will immediately be sent an `Op 2 HELLO` payload containing the heartbeat interval (in milliseconds) that the client should use when sending heartbeat messages to the server.

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

Heartbeat Acknowledged

```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 will be able to receive/send payloads immediately after this is received.</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 notify the server of new data which will then be routed to the correct consumer appropriately.</td><td>Client (producer only)</td></tr><tr><td>REPLAY</td><td>7</td><td>Request a replay of payloads after the given lower bound, and optionally before a given upper bound.</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>1001</td><td>Server is shutting down</td></tr><tr><td>1007</td><td>Invalid or unrecognised JSON data was provided</td></tr><tr><td>4000</td><td>IDENTIFY payload expected but was not received</td></tr><tr><td>4001</td><td>Improper token was passed for IDENTIFY</td></tr><tr><td>4002</td><td>Duplicate connection opened</td></tr><tr><td>4003</td><td>Multiple IDENTIFY payloads received</td></tr><tr><td>4004</td><td>Unrecognised opcode was received</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/reference/streaming-api/websocket-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.