Opcodes
Every message has an op field. The table below is generated from the protocol definition, so it always matches what the gateway implements.
| Op | Name | Direction | Purpose |
|---|---|---|---|
| 0 | DISPATCH | Server to client | An event occurred |
| 1 | HEARTBEAT | Both | Keep the connection alive |
| 2 | IDENTIFY | Client to server | Authenticate with a token |
| 6 | RESUME | Client to server | Continue a dropped session |
| 7 | RECONNECT | Server to client | Reconnect and resume |
| 9 | INVALID_SESSION | Server to client | Identify again |
| 10 | HELLO | Server to client | First message, gives the heartbeat interval |
| 11 | HEARTBEAT_ACK | Server to client | Heartbeat received |
A client may send HEARTBEAT, IDENTIFY and RESUME. Sending any other opcode, or a number that is not in the table, closes the connection with 4001.
Message shapes
Each section below says who sends the message, lists the fields in d with their types, and shows a full frame. A frame is the envelope from connection lifecycle: op, d, and on op 0 also s and t.
Each opcode
DISPATCH
Op 0. An event occurred. Carries the events.
- Server sends
HEARTBEAT
Op 1. Keep the connection alive.
- You send
- Server sends
| Field | Type | Description |
|---|---|---|
last_seq | number or null | Sequence number of the last event you processed, or null if you have not received one yet. |
This table covers the heartbeat you send. When the server sends a heartbeat, d is null and you answer with one of yours straight away.
{ "op": 1, "d": { "last_seq": 1234 }}IDENTIFY
Op 2. Authenticate with a token.
- You send
| Field | Type | Description |
|---|---|---|
token | string | Your gateway token. It is sent in this message and nowhere else. |
{ "op": 2, "d": { "token": "<your token>" }}RESUME
Op 6. Continue a dropped session.
- You send
| Field | Type | Description |
|---|---|---|
session_id | string | The session_id from READY. |
seq | number | Sequence number of the last event you processed. |
There is no token in RESUME.
{ "op": 6, "d": { "session_id": "<from READY>", "seq": 1234 }}RECONNECT
Op 7. Reconnect and resume.
- Server sends
No fields. Close the connection, reconnect and resume.
INVALID_SESSION
Op 9. Identify again.
- Server sends
| Field | Type | Description |
|---|---|---|
resumable | boolean | Always false. The session cannot be resumed, so identify afresh. |
{ "op": 9, "d": { "resumable": false }}HELLO
Op 10. First message, gives the heartbeat interval.
- Server sends
| Field | Type | Description |
|---|---|---|
heartbeat_interval | number | How often to send HEARTBEAT, in milliseconds. |
{ "op": 10, "d": { "heartbeat_interval": 45000 }}HEARTBEAT_ACK
Op 11. Heartbeat received.
- Server sends
d is null.