brainlet/resources/Docs/DOCS.md

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.

JSON data format:

Field	Description
pingInterval	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.
supportedAttributes	An array of attributes supported by the server. If a client requests an unsupported attribute, it is disconnected from the server.

Example:

0@{"pingInterval":14750,"supportedAttributes":["PRESENCE_UPDATES"]}

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
attributes	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","attributes":["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 attributes, 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	An ObjectId

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

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)