6 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 |
Example:
1@{"token":"my totally real token"}
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.
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.
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) |