Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Server Emojis

Emoji’s uploaded to the server can be configured to be used across all the channels in the server.

Text Channels

Text channels provides a chatroom that’s typically oriented around a specific topic. Users in the text channel can send, receive, and interact with messages. Text channels are the primary means of communication and are the default channel type.

Replies

Replies allow a user to reference a prior message in a text channel when sending a new message. The referenced message is typically displayed as a small quote above the new message, along with a link to navigate to that old message in scollback.

Reactions

Reactions allow users to “react” to a message in a text channel using an emoji. These emojis can either be the standard unicode emojis, or custom emojis defined by the server. See more about server emojis on their documentation page.

Chapter 1

Gateway

The gateway is a WebSocket endpoint that a client connects to for exchanging events between the client and the server.

ws(s)://<url>/gateway

Control Flow

The flow for connecting to the gateway endpoint is:

  1. Client makes a WebSocket connection to the gateway URL.
  2. When the server is ready, it sends a GatewayHandshake message to the client identifying the server’s version and capabilities.
  3. After the client receives the handshake it sends a GatewayIdentify message to the server with information about the client.
  4. The gateway server creates a server-side session for the client, and starts a the gateway session tasks.

Once that flow is complete, the gateway starts listening for new client-to-server gateway events from the client WebSocket, and forwards server-to-client events from the server to the WebSocket.

Encoding

The gateway protocol is defined in Protobuf, but thanks to the flexibility of prost and serde_json the gateway supports both Protobuf and JSON messages.

Important

The structure of the JSON encoding is slightly modified compared to the default Protobuf encoding.

Notably, the JSON representation of the oneof Protobuf types uses Serde’s enum representation settings to represent the JSON objects better for web use. See the API reference for details.

To set the encoding the client want’s to receive from the server, the client can specify the ?encoding=[protobuf|json] query parameter on the WebSocket connection URL. Note that this only sets the encoding received by the client from the server (see below for server-to-client encoding).

The gateway server automatically decides what encoding to use for messages received from clients based on if they’re text or binary WebSocket messages.

  • If the message is a binary message, the server assumes that Protobuf decoding is to be used.
  • If the message is a text message, the server assumes that JSON decoding is the be used.

Versioning

The gateway protocol defined using a Protobuf schema and versioned with semantic versioning.

When a client connects to the gateway a handshake message is sent to the client indicating the latest gateway protocol version that the server supports. A client can also specify the protocol version it wants to talk as a ?version=x query parameter on the gateway websocket endpoint.

Gateway v0