brainlet/resources/Docs/DOCS.md

6.3 KiB

Waffle API docs

Gateway

Waffle uses a WebSocket gateway to transmit various updates from the server to the client and vice-versa (new message, user disconnecting, connect to voice, etc.)

Gateway Payload format

All payloads sent through the gateway are string payloads. They all start with a number represeting the "instruction", followed by a "@" character (to delimit the instruction number from the rest of the payload), after which comes the data for the specific instruction.

Example packet:

23@this is my payload data

Note for the example above: The "this is my payload data" text should not be user controlled. If user controlled input is required, it must be sanitized and/or passed as a JSON field.

Packets can also have JSON as a payload:

32@{"name":"Alice"}

Instructions

0:HELLO

Part of handshake, Server to client

Sent by the server to the client as soon as possible after they connect to the gateway.

This payload contains a pingInterval property. Every pingInterval, the client must send a packet simply containing 7@1. This is the ACTION_PING payload. If the client does not send this payload at the right time, it is disconnected.

Example:

0@{"pingInterval":14750}

1:YOO

Part of handshake, Client to server

Sent by the client as soon as possible after receiving the HELLO instruction.

JSON data format:

Field Description
token The authentication token
roles An array of attributes the client wants the server to enable. The current possible values are: PRESENCE_UPDATES (required for presence updates to be sent to the client)

Example:

1@{"token":"my totally real token","roles":["PRESENCE_UPDATES"]}

If the token is invalid, or the connection is otherwise rejected, the client should be disconnected as soon as possible, and no YOO_ACK should be sent.

2:YOO_ACK

Part of handshake, Server to client

Sent by the server as soon as possible after processing the YOO payload from the client.

JSON data format:

Field Description
user A message author object
session_id A UUIDv4
channels An array of channels

Example:

2@{}

3:ACTION_CREATE_MESSAGE

Auth required, Client to server

Sent by the client when sending a message.

JSON data format:

Field Description
content The text content of the message
channel An object that contains "_id", the id of the channel to send the message to

Example:

3@{"content":"i hate you","channel":{"_id":"totally real channel id"}}

4:EVENT_NEW_MESSAGE

Auth required, Server to client

Sent by the server when a new message is created in a channel the client is subscribed to.

JSON data format: Message object

5:ACTION_UPDATE_STATUS

Auth required, Client to server

Sent by the client when updating status. Usually, this packet is sent as soon as possible after getting YOO_ACK to indicate the client is online.

This packet is deprecated and reserved for future use

JSON data format:

Field Description
status Can be 0(STATUS_OFFLINE) or 1(STATUS_ONLINE)
status_text Custom status text, max 50 characters, min 1 non-whitespace character, trimmed

Example:

5@{"status":1,"status_text":"hello"}

6:EVENT_CHANNEL_MEMBERS

Auth required, Server to client

An object containing a list of user presences which were updated, where the keys are the user ids and the values are user presence objects.

This packet is only sent if the user has PRESENCE_UPDATES in their roles, specified in YOO.

Example:

6@{"userid":{_id:"userid",username:"username123",status:1,status_text:"hello"}}

7:ACTION_PING

Auth required, Client to server

Sent by the client every pingInterval. The payload of this packet must always be 1.

Example:

7@1

21:ACTION_VOICE_REQUEST_SESSION

Auth required, Client to server

Sent by the client whenever it wants to initiate a voice session in a specific channel.

JSON data format:

Field Description
channel An object that contains "_id", the id of the channel to connect to

22:EVENT_VOICE_ASSIGN_SERVER

Auth required, Server to client

Sent by the server when a voice server has been assigned to a channel session.

JSON data format:

Field Description
reportTo The IP and port of the voice server to connect to
channel An object that contains "_id", the id of the channel

Voice server gateway

Voice server signaling is done through a websocket gateway. This gateway is specified by the reportTo property in EVENT_VOICE_ASSIGN_SERVER.

23:ACTION_VOICE_CONNECTION_REQUEST

Client to server

Field Description
token The authentication token
channel An object that contains "_id", the id of the channel to connect to
offer An SDP payload; the webrtc offer from the client

24:EVENT_VOICE_CONNECTION_ANSWER

Auth required, Server to client

Field Description
session_id A UUIDv4
answer An SDP payload; the webrtc answer from the server

Objects and data types

Message object

Field Description
content The text content of the message (max 2000 characters, min 1 character, trimmed)
channel A message channel object
author A message author object
_id A UUIDv4

Message channel object

Used mostly for messages.

Field Description
_id The id of the channel
name The name of the channel

Channel object

Field Description
_id The id of the channel
name The name of the channel
creator A user object

User object

Field Description
_id The id of the user
name The name of the user
color A hex color that represents that user

Message author object

Used mostly for messages.

Field Description
_id The id of the user
name The name of the user

User presence object

Field Description
_id The id of the user
name The name of the user
status The status of the user (see ACTION_UPDATE_STATUS)
status_text The text status of the user (see ACTION_UPDATE_STATUS)