Sock Chat Protocol Information

The 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, sent as an integer. The packet identifiers are as follows.

Some instructions are specific to newer revisions of the protocol and some instructions behave differently in newer revisions, all versions are documented but it is recommended you use the latest one. If a packet is marked as deprecated and you only aim to implement the latest version, you may omit it in your implementation as it will never be sent.

The current stable version of the protocol is Version 1.

Client

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.

Version 2
int 32-bit Unix timestamp
Version 1
int User ID

Packet 1: Authentication

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

Version 1
...any Any amount of data required to complete authentication

Packet 2: Message

Informs the server that the user has sent a message.

Required commands for Version 1 are described lower in the document.

Version 2
string Channel name
...string Message text, additional packet parameters should be glued on the server using \t
Version 1
int User ID
...string Message text, additional packet parameters should be glued on the server using \t

Packet 3: Upgrade

Informs the server that this client supports a newer version of the protocol. This should always be the first thing you send if you want to upgrade the connection, if any other packet is sent beforehand, this one will be ignored and the session will operate in version 1 mode. An upgrade packet containing any version below 2 should be ignored.

Version 2
int Version number

Server

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

Packet 0: Pong

Response to client packet 0: Ping.

Version 2
int 32-bit Unix timestamp when the packet was handled by the server
Version 1
string The literal string pong

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.

This packet behaves differently between version 1 and 2: In version 1 this packet is only sent to the channel that the user is about to join, in version 2 this packet is sent server wide.

Successful authentication response

Informs the client that authentication has succeeded.

Version 2
string Literal string y for yes
int Session User ID
string Username
color (int) Username color in packed format, documented below
permissions (string) User permissions, documented below
string Default channel the user will join following this packet
Version 1
string Literal string y for yes
int Session User ID
string Username
string CSS username color
permissions (string) User permissions, documented below
string Default channel the user will join following this packet

Failed authentication response

Informs the client that authentication has failed.

Version 2
string Literal string n for no
string Reason for failure.
  • auth: Authentication data is invalid.
  • conn: User has exceeded the maximum amount of connections per user.
  • baka: User attempting to authenticate is banned.
int If baka; A 32-bit Unix timestamp indicating the length of the ban
Version 1
string Literal string n for no
string Reason for failure.
  • authfail: Authentication data is invalid.
  • userfail: Username in use.
  • sockfail: A connection has already been started (used to cap maximum connections to 5 in SharpChat).
  • joinfail: User attempting to authenticate is banned.
int If joinfail; A 32-bit Unix timestamp indicating the length of the ban

User joining

Informs the client that a user has joined.

Version 2
int 32-bit Unix timestamp of when the user joined
int User ID
string Username
color (int) Username color in packed format, documented below
permissions (string) User permissions, documented below
int Event ID
Version 1
int 32-bit Unix timestamp of when the user joined
int User ID
string Username
string CSS username color
permissions (string) User permissions, documented below
int Event ID

Packet 2: Chat message

Informs the client that a chat message has been received.

Version 2
string Channel name
int 32-bit Unix timestamp of when the message was received by the server
int User ID. If -1 this message is an informational message from the server and the next field takes on a special form.
string Message, NOT SANITISED
int Event ID
message flags (string) Message flags, documented below
Version 1
int 32-bit Unix timestamp of when the message was received by the server
int User ID. If -1 this message is an informational message from the server and the next field takes on a special form.
string

Message, sanitised by the server

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.

int Message type.
  • 0 for a normal informational message.
  • 1 for an error.
string An id of a string in the legacy language files.
...string Any number of parameters used to format the language string.

int Event ID
message flags (string) Message flags, documented below

Packet 3: User disconnect

Informs the client that a user has disconnected.

Version 2
int User ID
string One of four disconnect reasons.
  • leave: The user gracefully left, e.g. "x logged out".
  • timeout: The user lost connection unexpectedly, e.g. "x timed out".
  • kick: The user has been kicked, e.g. "x has been kicked".
  • flood: The user has been kicked for exceeding the flood protection limit, e.g. "x has been kicked for spam".
int 32-bit Unix timestamp of when the user disconnected
int Event ID
Version 1
int User ID
string Username
string One of four disconnect reasons.
  • leave: The user gracefully left, e.g. "x logged out".
  • timeout: The user lost connection unexpectedly, e.g. "x timed out".
  • kick: The user has been kicked, e.g. "x has been kicked".
  • flood: The user has been kicked for exceeding the flood protection limit, e.g. "x has been kicked for spam".
int 32-bit Unix timestamp of when the user disconnected
int Event ID

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.

Version 1
int Channel information update event ID.
  • 0: A channel has been created.
  • 1: A channel has been updated.
  • 2: A channel has been deleted.

Sub-packet 0: Channel creation

Informs the client that a channel has been created.

Version 1
string The name of the new channel
bool Indicates whether the channel is password protected
bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs

Sub-packet 1: Channel update

Informs the client that details of a channel has changed.

Version 1
string The old/current name of the channel
string The new name of the channel
bool Indicates whether the channel is password protected
bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs

Sub-packet 2: Channel deletion

Informs the client that a channel has been deleted

Version 1
string The name of the channel that has been deleted

Packet 5: Channel switching

This packet informs the client about channel switching.

Version 1
int Channel information update event ID.
  • 0: A user joined the channel. Sent to all users in said channel.
  • 1: A user left the channel. Sent to all users in said channel.
  • 2: The client is to forcibly join a channel.

Sub-packet 0: Channel join

Informs the client that a user has joined the channel.

In version 1 this packet is NOT sent when the user first connects to the server. In version 2 this packet is sent regardless.

Version 2
int User ID
int Event ID
Version 1
int User ID
string Username
string CSS username color
int Event ID

Sub-packet 1: Channel departure

Informs the client that a user has left the channel.

Version 1
int User ID
int Event ID

Sub-packet 2: Forced channel switch

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

Version 1
string The name of the channel that the user has been switched to

Packet 6: Message deletion

Informs the client that a message has been deleted.

Version 1
int Event ID of the deleted message

Packet 7: Context information

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

Version 1
int Context event ID.
  • 0: Users present in the current channel.
  • 1: A message already in the channel, occurs more than once per channel.
  • 2: Channels on the server.

Sub-packet 0: Existing users

Informs the client about users already present in the channel.

Version 1
int Amount of users present in the channel
Context User An amount of repetitions of this object based on the number in the previous param, the object is described below
Context User object
Version 2
int User ID
string Username
color (int) Username color in packed format, documented below
permissions (string) User permissions, documented below
bool Whether the user should be visible in the users list
Version 1
int User ID
string Username
string CSS username color
permissions (string) User permissions, documented below
bool Whether the user should be visible in the users list

Sub-packet 1: Existing message

Informs the client about an existing message in a channel.

Version 2
int 32-bit Unix timestamp
int User ID
string Username
color (int) Username color in packed format, documented below
permissions (string) User permissions, documented below
string Message text, functions the same as described in Packet 2: Chat message
int Event ID
bool Whether the client should notify the user about this message
message flags (string) Message flags, documented below
Version 1
int 32-bit Unix timestamp
int User ID
string Username
string CSS username color
permissions (string) User permissions, documented below
string Message text, functions the same as described in Packet 2: Chat message
int Event ID
bool Whether the client should notify the user about this message
message flags (string) Message flags, documented below

Sub-packet 2: Channels

Informs the client about the channels on the server.

Version 1
int Amount of channels on the channel
Context Channel An amount of repetitions of this object based on the number in the previous param, the object is described below
Context Channel object
Version 1
string Channel name
bool Indicates whether the channel is password protected
bool Indicates whether the channel is temporary, meaning the channel will be deleted after the last person departs

Packet 8: Context clearing

Informs the client that the context has been cleared.

DEPRECATED IN VERSION 2

Version 1
int Number indicating what has been cleared.
  • 0: The message list has been cleared.
  • 1: The user list has been cleared.
  • 2: The channel list has been cleared.
  • 3: Both the message and user listing have been cleared.
  • 4: The message, user and channel listing have all been cleared.

Packet 9: Forced disconnect

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

Version 1
bool
  • 0: The client has been kicked, can reconnect immediately.
  • 1: The client has been banned, can reconnect after the timestamp in the next param has expired.
int A 32-bit Unix timestamp containing the ban expiration date and time

Packet 10: User update

Informs that another user's details have been updated.

Version 2
int User ID of the affected user
string New username
color (int) Username color in packed format, documented below
permissions (string) User permissions, documented below
bool Indicates a silent name update.
Version 1
int User ID of the affected user
string New username
string New CSS username color
permissions (string) User permissions, documented below

Packet 11: Upgrade acknowledgement

Responds to the client about its upgrade request through Packet 3: Upgrade.

The client must continue to operate as if it's talking to a Version 1 server until this packet is received. This requirement does hold Packet 1: Authentication in a strangehold, but luckily there's no reason to alter that packet at all due to its whatever nature.

Version 2
bool Indicates whether the version upgrade was successful
int If successful the current version will be returned. If unsuccessful the latest supported version should be returned which the client could use to decide to either disconnect or reattempt to upgrade

User Permission String

The User Permission String consists out of five (5) parts concatenated by a space operator, indentified in most languages as the escape sequence and defined as the ASCII character 0x20. In the original specification it appeared as if custom permission flags were possible, these have always gone completely unused and should thus be avoided. The parts are as follows:

Message Flags

The Message Flags alter how a message should be displayed to the client, these are all boolean values. I'm not entirely sure if these allowed for custom flags, but much like the custom flags in the User Permission String, these have gone unused and should thus, also, be avoided. The parts are as follows:

As an example, the most common message flagset is 10010.

Packed color format

Starting with Version 2 colors are no longer sent as textual CSS colors, rather they're sent as a more easy to work with integer format.

The format is pretty simple and comes in the form of a signed 32-bit integer in the following format: 0xFFRRGGBB. FF is reserved for flags, although the highest bit goes unused as to avoid clashing with the sign bit. RR is the byte containing the red color value, GG contains green and BB contains blue.

The only flag thusfar is 0x40 for indicating that the parent color should be inherited and the included color bytes should be ignored.

Here's some C code showing an example of converting the integer color to a CSS color string;

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define FLAG_INHERIT (0x40000000)

char* color_to_css(int raw) {
    if(raw & FLAG_INHERIT)
        return "inherit";

    char* css = (char*)malloc(17);
    memset(css, 0, 17);

    sprintf(
        css,
        "rgb(%d,%d,%d)",
        (raw >> 16) & 0xFF,
        (raw >>  8) & 0xFF,
         raw        & 0xFF
    );

    return css;
}

Version 1 Bot Messages

Formatting IDs sent by user -1 in Version 1 of the protocol.

Informational
String Description Arguments
say Just echoes the arguments in a message. The message.
silence Informs the client that they have been silenced.
unsil Informs the client that they are no longer silenced.
silok Informs the client that they have successfully silenced another user. The username of the silenced user.
usilok Informs the client that they have successfully removed the silencing from another user. The username of the unsilenced user.
flwarn Informs the client that they are risking being kicking for flood protection (spam).
unban Informs the client that they have successfully removed the ban from a user or ip address.
banlist Provides a list with banned users and IP addresses. Sets of "<a href="javascript:void(0);" onclick="Chat.SendMessageWrapper('/unban '+ this.innerHTML);">{0}</a>" where {0} is the username of the banned user or the banned IP address. The set is separated by ", "
who Provides a list of users currently online. Sets of "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", "
whochan Provides a list of users currently online in a specific channel. Sets of "<a href="javascript:void(0);" onclick="UI.InsertChatText(this.innerHTML);">{0}</a>" where {0} is the username of a user. The current online user is highlighted with " style="font-weight: bold;"" before the closing > of the opening <a> tag. The set is separated by ", "
join Informs the client that a user connected with the server. The username of said user.
jchan Informs the client that a user moved into the channel. The username of said user.
leave Informs the client that a user disconnected from the server. The username of said user.
lchan Informs the client that a user moved out of the channel. The username of said user.
kick Informs the client that a user has disconnect because they got kicked. The username of said user.
flood Informs the client that a user has disconnect because they got kicked for flood protection. The username of said user.
nick Informs the client that a user has changed their nickname. The first argument is the previous username of said user, the second argument is their new username.
crchan Informs the client that they have successfully created a channel. The name of the channel.
delchan Informs the client that they have successfully deleted a channel. The name of the channel.
cpwdchan Informs the client that they have successfully changed the password of the channel.
cprivchan Informs the client that they have successfully changed the hierarchy level required for the channel.
ipaddr Shows the IP address of another user. First argument is the username, second argument is the IP address.
Error
String Description Arguments
generr Generic fallback error.
silerr Informs the client that the user they tried to silence had already been silenced.
usilerr Informs the client that the user whose silence they tried to revoke hasn't been silenced.
silperr Informs the client that they are not allowed to silence that user.
usilperr Informs the client that they are not allowed to remove the silence from that user.
silself Informs the client that they cannot silence themselves.
delerr Informs the client that they are not allowed to delete a message.
notban Informs the client that a username or IP address is not banned. The provided username or IP address.
whoerr Informs the client that they do not have access to the channel they specified for the /who command. The provided channel name.
cmdna Tells the client they're not allowed to use a command. First argument is the name of the command.
nocmd Tells the client the command they tried to run does not exist. First argument is the name of the command.
cmderr Tells the client that they formatted the last command incorrectly.
usernf Tells the client that the user they requested was not found on the server. The requested username.
kickna Tells the client that they are not allowed to kick a given user. Username of the user they tried to kick.
samechan Tells the client that they are already in the channel they are trying to switch to. The name of the channel.
ipchan Tells the client that they aren't allowed to switch to the provided channel. The name of the channel.
nochan Tells the client that the channel they tried to switch to does not exist. The name of the channel.
nopwchan Tells the client that the channel they tried to switch to requires a password. The name of the channel.
ipwchan Tells the client that the password to tried to switch to the channel to was invalid. The name of the channel.
inchan Informs the client that the channel name contained invalid characters.
nischan Tells the client that a channel with that name already exists. The name of the channel.
ndchan Tells the client that they're not allowed to delete that channel. The name of the channel.
namchan Tells the client that they're not allowed to edit that channel. The name of the channel.
nameinuse Tells the client that the nickname they tried to use is already being used by someone else. The name.
rankerr Tells the client that they're not allowed to do something to a user because they have a higher hierarchy than them.

Version 1 Commands

Actions sent through messages prefixed with / in Version 1 of the protocol. Arguments are described as [name], optional arguments as [name?].

Name Action Expected bot messages
/afk [reason?] Marks the current user as afk, the first 5 characters from the user string are prefixed uppercase to the current username prefixed by &lt; and suffixed by &gt;_ resulting in a username that looks like <AWAY>_flash if /afk away is ran by the user flash. If no reason is specified "AFK" is used.
/nick [name?] Temporarily changes the user's nickname prefixed with ~. 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.
  • cmdna: Not allowed to change own nickname.
  • nameinuse: Someone else is using the username.
  • nick: Username has changed.
/msg [username] [message]
/whisper [username] [message]
Sends a private message to another user.
  • cmderr: Missing username and/or message arguments.
  • usernf: User not found.
/me [message]
/action [message]
Sends a message but with flags 11000 instead of the regular 10010, used to describe an action.
/who [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.
  • nochan: The given channel does not exist.
  • whoerr: The user does not have access to the channel.
  • whochan: Listing of users in a channel.
  • who: Listing of users.
/delete [channel name or message id] If the argument is entirely numeric this function acts as an alias for /delmsg, otherwise /delchan.
/join [channel] Switches the current user to a different channel.
  • nochan: The given channel does not exist.
  • ipchan: The user does not have access to the channel.
  • ipwchan: The provided password was invalid.
  • nopwchan: A password is required to enter the given channel.
/create [hierarchy?] [name] Creates a new channel.
  • cmdna: Not allowed to create channels.
  • cmderr: Command isn't formatted correctly.
  • rankerr: Tried to set channel hierarchy higher than own.
  • inchan: Given name contained invalid characters.
  • nischan: A channel with the given name already exists.
  • crchan: Successfully created channel.
/delchan [name] Deletes an existing channel.
  • cmderr: Command isn't formatted correctly.
  • nochan: No channel with the given name exists.
  • ndchan: Not allowed to delete this channel.
  • delchan: Deleted channel.
/password [password?]
/pwd [password?]
Changes the password for a channel. Specify no argument to remove the password.
  • cmdna: Not allowed to change the password.
  • cpwdchan: Success.
/privilege [hierarchy]
/rank [hierarchy]
/priv [hierarchy]
Changes what user hierarchy is required to enter a channel.
  • cmdna: Not allowed to change hierarchy.
  • rankerr: Missing rank argument or trying to set hierarchy to one higher than their own.
  • cprivchan: Success.
/say [message] Broadcasts a message as the server to all users in all channels.
  • cmdna: Not allowed to broadcast.
  • say: Broadcast message.
/delmsg [message id] Deletes a message.
  • cmdna: Not allowed to delete messages.
  • cmderr: Invalid arguments.
  • delerr: The message does not exist, or the user's hierarchy is lower than the sender.
/kick [user] [time?] Kicks a user from the server. If no time is specified the kick expires immediately.
  • cmdna: Not allowed to kick users.
  • usernf: User not found.
  • kickna: Sender is trying to kick themselves, someone with a higher hierarchy or someone that's already banned.
  • cmderr: Provided time is invalid.
/ban [user] [time?] Kicks a user and IP address from the server. If no time is specified the kick will never expire.
  • cmdna: Not allowed to kick users.
  • usernf: User not found.
  • kickna: Sender is trying to kick themselves, someone with a higher hierarchy or someone that's already banned.
  • cmderr: Provided time is invalid.
/unban [user]
/pardon [user]
Revokes the ban of a user.
  • cmdna: Not allowed to revoke user bans.
  • notban: User is not banned.
  • unban: Success.
/unbanip [user]
/pardonip [user]
Revokes the ban of an ip address.
  • cmdna: Not allowed to revoke ip bans.
  • notban: IP address is not banned.
  • unban: Success.
/bans
/banned
Retrieves the list of banned users and ip addresses.
  • cmdna: Not allowed to revoke ip bans.
  • banlist: List of bans.
/silence [username] [time?] Silences a user. If the time argument is not specified the silence is indefinite.
  • cmdna: Not allowed to silence users.
  • usernf: User not found.
  • silself: Tried to silence self.
  • silperr: Tried to silence user of higher hierarchy.
  • silerr: User is already silenced.
  • cmderr: Time isn't formatted correctly.
  • silence: Informs the user they have been silenced.
  • silok: Tells the sender that the user has been silenced.
/unsilence [username] Revokes a silence.
  • cmdna: Not allowed to revoke silences.
  • usernf: User not found.
  • usilperr: Tried to revoke silence of user of higher hierarchy.
  • usilerr: User isn't silenced.
  • unsil: Informs the user that their silence has been revoked.
  • usilok: Tells the sender that the user's silence has been revoked.
/ip [username]
/whois [username]
Gets a user's IP address.
  • cmdna: Not allowed to view IP addresses.
  • usernf: User not found.
  • ipaddr: IP address of user.
Sock Chat V1 was created by MallocNull
Markdown parsing by a modified version of Parsedown
Maintained flashwave
This page is automatically generated using Protocol.md from the Sharp Chat repository.