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) |