This is not a guide to using the webchat, this a reference point for writing clients.
Satyr's webchat is based on [socket.io](https://socket.io/), you can find clients for [Java](https://github.com/socketio/socket.io-client-java), [C++](https://github.com/socketio/socket.io-client-cpp), [Swift](https://github.com/socketio/socket.io-client-swift), [Dart](https://github.com/rikulo/socket.io-client-dart), and probably more.
Socket.IO is loosely reminiscent of IRC in that you will receive events from the server and sent events to it. The following is a list of incoming and outgoing events you will need to handle or send. If you would like to see examples, templates/chat.html is the implementation used in the webclient by satyr.
These are events you will recieve from the server that need to be handled in some way.
## MSG
A MSG event is a chat message. It will have data attached in the following JSON format:
```
{
nick: "nickname of the sending user",
msg: "the text of the message",
room: "the room the message was sent to"
}
```
## ALERT
An ALERT event is a message from the server to a room. It is just a string containing the plaintext message. Alerts notify a user about things like nickname changes, users who are kicked or banned, and errors.
## JOINED
A JOINED event notifies the client that a new user has joined a room they are in. It's a JSON message in the following format:
```
{
nick: "the user that joined",
room: "the name of the room"
}
```
## LEFT
A LEFT event notifies the client that a user has left a room they are in. It's a JSON message in the following format:
```
{
nick: "the user that left",
room: "the name of the room"
}
```
## LIST
A LIST event will only be emitted by the server in response to receiving a LIST event from the client. It is a string containing the list of users in a room, separated by commas.
# Outgoing Events
These are events sent from the client to request that the server do something.
## NICK
This is a request to set the client's nickname. The data attached to a NICK event should be a JSON object in the following format. The password field is optional, and only required for registered users.
During the initial connect of the client, the server will check for the "Authorization" cookie. If the cookie is a valid, signed JWT the client will be assigned the nickname of the user that cookie belongs to. If it doesn't exist or is invalid, the client will be assigned a nickname of the form Guest+some integer.
This is a request to join a room and be notified of its events. The attached data should be a string containing the name of the room.
The server will send the client an alert notifying them of having joined the room, or some error.
## LEAVEROOM
This is a request to leave a room and no longer be notified of its events. The attached data should be a string containing the name of the room.
## LIST
This is a request for a list of users in a room. It should be a JSON object of the following format:
`{room: "the name of the room"}`
## KICK
This is a request to kick a user from a room. It can only be done by the owner of the room. It should be a JSON object of the following format:
```
{
nick: "the user to kick",
room: "the room to kick them from"
}
```
## BAN
This is a request to ban a user from a room. It can only be done by the owner of the room. All bans are based on IP. It should be a JSON object of the following format:
```
{
nick: "the user to ban",
room: "the room to ban them from",
length: 30
}
```
The length field is time in minutes.
## LISTBAN
This is a request for a list of IP adresses banned from a room. It should be a JSON object of the following format:
`{room: "the name of the room"}`
The server will reply with an ALERT that contains a list of IP addresses separated by commas.
## UNBAN
A request to unban an IP address. It can only be done by the owner of the room. It should be a JSON object of the following format:
Sending more than 10 messages per second will cause the server to kick your client. If kicked this way 3 times, the client will be banned for 20 minutes.
Clients who successfully authenticate as a registered user, through either a password or a signed JWT, can ignore nickname collision and have as many connections as they wish.