Sock Chat Protocol Information

The Sock Chat protocol operates on a websocket in text mode. Messages sent between the client and server are a series of concatenated strings delimited by the vertical tab character, represented in most languages by the escape sequence \t and defined in ASCII as 0x09. The first string in this concatenation must be the packet identifier.

Updated behaviour is defined through capabilities. Further documentation on their behaviour will be added at a later date.

Types

bool

A value that indicates a true or a false state. 0 represents false and anything non-0 represents true, please stick to 1 for representing true though.

int

Any number ranging from -9007199254740991 to 9007199254740991, Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER in JavaScript.

string

Any printable unicode character, except \t which is used to separate packets.

timestamp

Extends int, contains a second based UNIX timestamp.

user name

A string containing a user's name.

If the user currently has an AFK tag set through the /afk, it is prefixed by <AFK>_. The AFK text can be replaced by any text supplied to the /afk command as an argument, the original PHP Sock Chat and SharpChat force this text to uppercase and limit it to 5 characters.

If prefixed by a ~, it is not the user's actual name but a nick name.

channel name

A string containing only alphanumeric characters (any case), - or _.

colour

Any valid value for the CSS colour property. Further documentation can be found on MDN.

message flags

Message flags alter how a message should be displayed to the client, these are all bool values. The parts are as follows:

As an example, the most common message flagset is 10010. This indicates a bold username with a colon separator.

user perms

User permissions are a set of flags separated by either the form feed character (\f / 0x0C) or a space (' ' / 0x20). The reason there are two options is due to a past mixup that we now have to live with. Which of the methods is used remains consistent per server however, so the result of a test can be cached.

Note that this string MAY be empty if sent by the bot user (-1).

Type Description
int Rank of the user. Used to determine what channels a user can access or what other users the user can moderate.
bool Indicates whether the user the ability kick/ban/unban others.
bool Indicates whether the user can access the logs. This should always be 0, unless the client has a dedicated log view that can be accessed without connecting to the chat server.
bool Indicates whether the user can set an alternate display name.
int Indicates whether the user can create channel. If 0 the user cannot create channels, if 1 the user can create channels but they are to disappear when all users have left it and if 2 the user can create channels that permanently stay in the channel assortment.

Client Packets

These are the packets sent from the client to the server.

Packet 0: Ping

Used to prevent the client from closing the session due to inactivity.

Type Description
string User ID of the current user.

Packet 1: Authentication

Takes a variable number of parameters that are fed into the authentication script associated with the chat.

Type Description
...string Any amount of data required to complete authentication.

Original Sock Chat phpBB format

Although the specification was never strict on the format, the original client and server combo included only a single authentication extension for phpBB. Flashii Hajime, Sakura and early Misuzu also used this same format.

Type Description
string User ID of the authenticating user.
string Session token for the authenticating user.

Flashii Chat format

In order to support multiple authentication methods more easily, Flashii Chat currently uses a format similar to the HTTP Authorization header, where the first field is the authentication method and the second field is the authentication token. Previously, this was achieved using prefixes to the session token part of phpBB format.

Type Description
string Authentication method, for example Bearer for an OAuth2 bearer token, or Misuzu for using the msz_auth cookie value.
string Authentication token, for example the OAuth2 bearer token value, or the Misuzu authentication cookie.

Packet 2: Message

Informs the server that the user has sent a message.

Commands are described lower in the document.

Type Description
string User ID of the current user.
string Message text, cannot contain a tab character \t.

Server Packets

These are the packets sent from the server to the client.

Packet 0: Pong

Response to client packet 0: Ping.

Type Description
string A string containing pong. Previously SharpChat sent the current Unix timestamp here, but has since been updated to conform to the Original Sock Chat server formatting.

Packet 1: Join/Auth

While authenticated this packet indicates that a new user has joined the server/channel. Before authentication this packet serves as a response to client packet 1: Authentication.

Successful authentication response

Informs the client that authentication has succeeded.

Type Description
string y to indicate a successful authentication attempt.
string User ID of the authenticated user.
user name User name of the authenticated user.
colour User colour of the authenticated user.
user perms Permissions for the authenticated user.
channel name Default channel the user will join following this packet.
int Maximum length for messages sent by the client. NOTE: While the original PHP server did not send this data, the bundled client did look for it.

Failed authentication response

Informs the client that authentication has failed.

Type Description
string n to indicate a failed authentication attempt.
string A reason string indicating the reason why the authentication attempt failed, options are listed below.
timestamp If included, indicates a ban expiration timestamp. Usually paired with the joinfail reason string.
Reason strings
Reason Explanation
authfail Provided authentication data cannot be verified with an existing user or session.
joinfail Authentication data was correct, but the user is banned. The third field will contain an expiration timestamp.
sockfail Current socket connection is already authenticated. PHP Chat did not allow the same user account to be in chat more than once. SharpChat allows simultaneous connections, so this is used to put a cap on the maximum amount of connections a single user may have. As of writing this, the maximum number is 5, however this may change in the future.
userfail A user with the same user name is already in chat. PHP Chat did not allow the same user account to be in chat more than once. SharpChat allows simultaneous connections, so this is used as a generic fallback reason in that implementation. If it occurs, a critical error happened on the backend.

User joining

Informs the client that a user has joined.

Type Description
timestamp Timestamp at which the user joined.
string User ID of the joining user.
user name User name of the joining user.
colour User colour for the joining user.
user perms Permissions for the joining user.
string Message ID associated with this event.

Packet 2: Chat message

Informs the client that a chat message has been received.

Type Description
timestamp Timestamp at which the message was received by the server.
string User ID of the author. If -1 the message body will contain a formatted informational message documented below.
string Message body. If this isn't an informational message, it is sanitised by the server: <, > and \n are replaced by &lt;, &gt; and <br/>. SharpChat also replaces \t with four sequential space characters.
string Message ID.
message flags Message flags.

Informational message formatting

If this is an informational message this field is formatted as follows and concatenated by the form feed character \f, respresented in ASCII by 0x0C. Bot message formats are described lower in the document.

Type Description
bool If 1, this message should be displayed as an error message. If 0, it should be displayed as a normal informational message.
string Informational message format name. List of formats is described below.
...string Any number of parameters required by the format string.

Packet 3: User disconnect

Informs the client that a user has disconnected.

Type Description
string User ID of the disconnecting user.
user name User name of the disconnecting user.
string Reason for disconnecting, described below.
timestamp Timestamp when the user disconnected.
string Message ID associated with this event.

Disconnect reasons

Reason Explanation
leave User gracefully left, e.g. "xyz logged out".
kick User got banned, kicked or otherwise unvoluntarily had their session terminated, e.g. "xyz has been kicked".
flood User got kicked for exceeding the flood protection limit, e.g. "xyz has been kicked for spam".
timeout User lost connection unexpectedly after not sending pings in a timely fashion, e.g. "xyz timed out". The original PHP Sock Chat implementation did not support this and was added later by SharpChat. Support could be added by modifying the language file, so we're letting this slide.

Packet 4: Channel event

This packet informs the user about channel related updates. The only consistent parameter across sub-packets is the first one described as follows.

Type Description
int Sub-packet ID.

Sub-packet 0: Channel creation

Informs the client that a channel has been created.

Type Description
channel name Name of the new channel.
bool Indicates whether the channel is password protected (non-0) or not (0).
bool Indicates whether the channel is temporary (non-0) or not (0). In the original PHP Chat implementation this would mean a channel gets deleted after the last person departs from it.

Sub-packet 1: Channel update

Informs the client that details of a channel has changed.

Type Description
channel name Previous name of the channel.
channel name New name of the channel.
bool Indicates whether the channel is password protected (non-0) or not (0).
bool Indicates whether the channel is temporary (non-0) or not (0). In the original PHP Chat implementation this would mean a channel gets deleted after the last person departs from it.

Sub-packet 2: Channel deletion

Informs the client that a channel has been deleted

Type Description
channel name Name of the channel to be deleted.

Packet 5: Channel switching

This packet informs the client about channel switching.

Type Description
int Sub-packet ID.

Sub-packet 0: Channel join

Informs the client that a user has joined the channel.

Type Description
string User ID of the user joining the channel.
user name User name of the user joining the channel.
colour User colour of the user joining the channel.
user perms Permissions of the user joining the channel.
string Message ID associated with this event.

Sub-packet 1: Channel departure

Informs the client that a user has left the channel.

Type Description
string User ID of the user leaving the channel.
string Message ID associated with this event.

Sub-packet 2: Forced channel switch

Informs the client that it has been forcibly switched to a different channel.

Type Description
channel name Name of the channel the current user is now present in.

Packet 6: Message deletion

Informs the client that a message has been deleted.

Type Description
string Message ID of the message to be deleted.

Packet 7: Context information

Informs the client about the context of a channel before the client was present.

Type Description
int Sub-packet ID.

Sub-packet 0: Existing users

Informs the client about users already present in the channel.

Type Description
int Amount of users present in the current channel.
A repetition of a number of fields based on the number above, described below.
Context user information
Type Description
string User ID of this already present user.
user name User name of this already present user.
colour User colour of this already present user.
user perms Permissions of this already present user.
bool If non-0 this user should be displayed in a user list, if 0 this user should be treated as invisible. Used by bot mods in the original PHP implementation.

Sub-packet 1: Existing message

Informs the client about an existing message in a channel.

Type Description
timestamp Timestamp at which the message was received by the server.
string User ID of the author. If -1 the message body will contain a formatted informational message documented below.
user name User name of the author of this message.
colour User colour of the author of this message.
user perms Permissions of the author of this message.
string Message body. If this isn't an informational message, it is sanitised by the server: <, > and \n are replaced by &lt;, &gt; and <br/>. SharpChat also replaces \t with four sequential space characters.
string Message ID.
bool If non-0 this message should trigger notifications (sounds, banners, etc) on the client.
message flags Message flags.

Sub-packet 2: Channels

Informs the client about the channels on the server.

Type Description
int Amount of channels on the server.
A repetition of a number of fields based on the number above, described below.
Context channel information
Type Description
channel name Name of the new channel.
bool Indicates whether the channel is password protected (non-0) or not (0).
bool Indicates whether the channel is temporary (non-0) or not (0). In the original PHP Chat implementation this would mean a channel gets deleted after the last person departs from it.

Packet 8: Context clearing

Informs the client that the context has been cleared. This packet can be safely ignored, its behaviour can be implicitly handled when required according to the table below.

Type Description
int Number indicating what data should be cleared. Modes are described below.

Context clear modes

Mode Explanation
0 Only the message history should be cleared. Does not normally occur.
1 Only the user list should be cleared. Does not normally occur.
2 Only the channel list should be cleared. Does not normally occur.
3 Clear the message history and user list. Occurs upon switching (or being switched) to another channel.
4 Clear the message history, user list and channel list. Does not normally occur.

Packet 9: Forced disconnect

Informs the client that they have either been banned or kicked from the server.

Type Description
bool If non-0, the next field will be defined and contain an expiration time. If 0, the user can rejoin immediately.
timestamp Ban expiration timestamp, present when the first field is non-0.

Packet 10: User update

Informs that another user's details have been updated.

Type Description
string User ID of the updated user.
user name New user name of the updated user.
colour New user colour for the updated user.
user perms New permissions for the updated user.

Bot Messages

Formatting IDs sent by user -1.

Informational

say: Broadcast

Just echo whatever is specified in the first argument.

Arguments

flwarn: Flood protection warning

Informs the client that they are risking getting kicked for flood protection (spam) if they continue sending messages at the same rate.

unban: Ban revocation confirmation

Informs the client that they have successfully revoked a ban on a user or an IP address.

banlist: List of banned entities

Provides the client with a list of all banned users and IP addresses.

Arguments

who: List of online users

Provides the client with a list of users currently online on the server.

Arguments

whochan: List of users in a channel.

Provides the client with a list of users currently online in a channel.

Arguments

join: User connected

Informs the client that a user just connected to the server.

Arguments

jchan: User joined channel

Informs the client that a user just joined a channel they're in.

Arguments

leave: User disconnected

Informs the client that a user just disconnected from the server.

Arguments

lchan: User left channel

Informs the client that a user just left a channel they're in.

kick: User has been kicked

Informs the client that another user has just been kicked.

Arguments

flood: User exceeded flood limit

Informs the client that another user has just been kicked for exceeding the flood protection limit.

Arguments

timeout: User has timed out

Informs the client that another user has been disconnected from the server automatically.

Arguments

nick: User has changed their nickname

Informs the client that a user has changed their nickname.

Arguments

crchan: Channel creation confirmation

Informs the client that the channel they attempted to create has been successfully created.

Arguments

delchan: Channel deletion confirmation

Informs the client that the channel they attempted to delete has been successfully deleted.

Arguments

cpwdchan: Channel password update confirmation

Informs the client that they've successfully changed the password of a channel.

cprivchan: Channel rank update confirmation

Informs the client that they've successfully changed the minimum required rank to join a channel.

ipaddr: IP address

Shows the IP address of another user to a user with moderation privileges.

Arguments

Errors

generr: Generic Error

Informs the client that Something went Wrong.

nocmd: Command not found

Informs the client that the command they tried to run does not exist.

Arguments

cmdna: Command not allowed

Informs the client that they are not allowed to use a command.

Arguments

cmderr: Command format error

Informs the client that the command they tried to run was incorrectly formatted.

Arguments

usernf: User not found

Informs the client that the user argument of a command contains a user that is not known by the server.

Arguments

rankerr: Rank error

Informs the client that they are not allowed to do something because their ranking is too low.

nameinuse: Name in use

Informs the the client that the name they attempted to choose is already in use by another user.

Arguments

whoerr: User listing error

Informs the client that they do not have access to the channel they tried to query.

Arguments

kickna: Kick or ban not allowed

Informs the client that they are not allowed to kick a user.

Arguments

notban: Not banned

Informs the client that the ban they tried to revoke was not in place.

Arguments

nochan: Channel not found

Informs the client that the channel they tried to join does not exist.

Arguments

samechan: Already in channel

Informs the client that they attempted to join a channel they are already in.

Arguments

ipchan: Channel join not allowed

Informs the client that they do not have sufficient rank or permissions to join a channel.

Arguments

nopwchan: No password provided

Informs the client that they must specify a password to join a channel.

Arguments

ipwchan: No password provided

Informs the client that the password they provided to join a channel was invalid.

Arguments

inchan: Invalid channel name

Informs the client that the name they tried to give to a channel contains invalid characters.

nischan: Channel name in use

Informs the client that the name they tried to give to a channel is already used by another channel.

Arguments

ndchan: Channel deletion error

Informs the client that they are not allowed to delete a channel.

Arguments

namchan: Channel edit error

Informs the client that they are not allowed to edit a channel.

Arguments

delerr: Message deletion error

Informs the client that they are not allowed to delete a message.

Commands

Actions sent through messages prefixed with /. Arguments are described as [name], optional arguments as [name?]. The . character is ignored in command names (replaced by nothing).

/afk: Setting status to away

Marks the current user as afk, the first 5 characters from the user string are prefixed uppercase to the current username prefixed by &amp;lt; and suffixed by &amp;gt;_ resulting in a username that looks like &lt;AWAY&gt;_flash if /afk away is ran by the user flash. If no reason is specified "AFK" is used.

Format

/afk [reason?]

/nick: Change nickname

Temporarily changes the user's nickname, generally with a prefix such as ~ to avoid name clashing with real users. If the user's original name or no argument at all is specified, the command returns the user's name to its original state without the prefix.

Format

/nick [name?]

Responses

/msg: Sending a Private Message

Sends a private message to another user.

Format

/msg [username] [message]

Aliases

Responses

/me: Describing an action

Sends a message but with flags 11000 instead of the regular 10010, used to describe an action.

Format

/me [message]

Aliases

/who: Requesting a user list

Requests a list of users either currently online on the server in general or in a channel. If no argument is specified it'll return all users on the server, if a channel is specified it'll return all users in that channel.

Format

/who [channel?]

Responses

/delete: Deleting a message or channel

Due to an oversight in the original implementation, this command was specified to be both the command for deleting messages and for channels. Fortunately messages always have numeric IDs and channels must start with an alphabetic character. Thus if the argument is entirely numeric this function acts as an alias for /delmsg, otherwise /delchan.

Format

/delete [channel name or message id]

Responses

Inherits the responses of whichever command is forwarded to.

/join: Joining a channel

Switches or joins the current user to a different channel.

Format

/join [channel] [password?]

Responses

/leave: Leaving a channel

Leave a specified channel.

Format

/leave [channel]

Responses

/create: Creating a channel

Creates a new channel.

Format

/create [rank?] [name...]

If the first argument is numeric, it is taken as the minimum required rank to join the channel. All further arguments are glued with underscores to create the channel name.

Responses

/delchan: Deleting a channel

Deletes an existing channel.

Format

/delchan [name]

Responses

/password: Update channel password

Changes the password for a channel. Removes the password if no argument is given.

Format

/password [password?]

Aliases

Responses

/rank: Update channel minimum rank

Changes what user rank is required to enter a channel.

Format

/rank [rank]

Aliases

Responses

/say: Broadcast a message

Broadcasts a message as the server/chatbot to all users in all channels.

Format

/say [message]

Responses

/delmsg: Deleting a message

Deletes a given message.

Format

/delmsg [message id]

Responses

/kick: Kick a user

Kicks a user from the serer. If not time is specified, then kick expires immediately.

Format

/kick [username] [time?]

Responses

/ban: Bans a user

Bans a user and their IP addresses from the server. If no time is specified the ban will never expire.

Format

/ban [user] [time?]

Responses

/pardon: Revokes a user ban

Revokes a ban currently placed on a user.

Format

/pardon [user]

Aliases

Responses

/pardonip: Revokes an IP address ban

Revokes a ban currently placed on an IP address.

Format

/pardonip [address]

Aliases

Responses

/bans: List of bans

Retrieves a list of banned users and IP addresses.

Format

/bans

Aliases

Responses

/ip: Retrieve IP addresses

Retrieves a user's IP addresses. If the user has multiple connections, multiple ipaddr responses may be sent.

Format

/ip [username]

Aliases

Responses

Sock Chat was created by reemo
Markdown parsing by a modified version of Parsedown
Maintained by flashwave
This page is automatically generated using Protocol.md from the Sharp Chat repository.
Loaded in 1.49159 seconds.