The ElzChat API consists of a number of pages expecting a POST request.
The request needs two parameters:
type, which indicates the type of request, and
data, a JSON string with the parameters,
with each always being either a string or a number (integer).
The Content-Type for the request has to be multipart/form-data.
application/x-www-form-urlencoded is not supported.
All pages return a JSON string with a error parameter, provided a POST-request is made.
It will equal "success" if everything went right or a error message in case of an error.
Requests that are not POST or do not use the correct paths will return a 404.
Following are general error messages, that can be given by any page.
"Wrong content-type." if the request does not use the multipart/form-data content-type,
"Invalid parameters." if any of the paramters are missing,
"Invalid JSON." if the data-parameter is not valid JSON,
"Invalid type." if the type is not correct for the page,
"Wrong parameters." if the data-JSON is missing or has invalid parameters,
"Authentication failure." if the token is not valid or the user no longer exists, and
"Unauthorised." if the user is unauthorised to execute the action.
There is also a websocket-API for recieving messages when updates to the chat, online users, and ElzPlace happen.
It is recommended to make use of this websocket-API to check for these updates.
In the JSON representations below only 1 entry in an array is shown,
but the response will usually have more than 1 entry.
When an error is thrown (error is not "success"),
only the error parameter will be present in the returned JSON.
/elzchat6/api/auth.php is responsible for user authentication.
User authentication in ElzChat works with a token-based system.
After requesting a token via auth.php, it can be used in all the other pages.
A token consists of 64 characters, in the ranges 0 - 9, A - Z, a - z.
| type | data | returned data | explanation | non-general errors |
|---|---|---|---|---|
| gettoken | {"username": string, "password": string} |
{"error": string, "token": string} |
Gets a token for a username with the given password. | "Incorrect username." if the username is incorrect."Incorrect password." if the password is incorrect for this username. |
| register | {"username": string, "password": string} |
{"error": string} | Registers a username with the given password. | "Username already exists." if the username is already in use."Username too long or empty." if the username is empty or more than 50 characters. |
| removetoken | {"token": string} | {"error": string} | Removes, therefore invalidates the given token. | "Nonexistent token." if the token does not exist. |
/elzchat6/api/user.php is responsible for getting and setting information about a user.
It allows getting and setting names, settings and other user specific information.
The data gotten with getuser consist of the folowing:
username, the actual name (used when logging in),
state, the current state of the user (-1 is banned, 0 is normal and 1 is admin),
nick, the nickname for this user (shows up in messages),
color, the color the user has selected (background color in messages),
image, currently unused (always default.png),
style, the style setting the user has selected (from 1 to 10),
sound, the sound setting the user has selected
(if a sound should be played when getting messages, 0 (no) or 1 (yes)),
total, the total setting the user has selected (total messages per page), and
enter, the enter setting the user has selected
(if pressing enter should send the message, 0 (no) or 1 (yes)).
| type | data | returned data | explanation | non-general errors |
|---|---|---|---|---|
| deleteuser | {"token": string, "id": number} |
{"error": string} | Deletes the user with the given userid. The token either needs to be for this user, or a user who is an admin. | "Invalid userid." if the userid is non-existent. |
| editdisplay | {"token": string, "id": number, "nick": string, "color": string} |
{"error": string} | Changes the display settings for the user with the given userid. The token either needs to be for this user, or a user who is an admin. The token must not be for a banned user. | "Color is invalid." if the color is not a valid #hhhhhh color."Nickname too long or empty." if the nickname is empty or more than 50 characters."Invalid userid." if the userid is non-existent. |
| editpassword | {"token": string, "id": number, "old": string, "new": string} |
{"error": string} | Changes the password for the user with the given userid, given the old and new password. The token either needs to be for this user, or a user who is an admin. The old password only has to match if the user is not an admin. | "Old password is incorrect." if the old password is not correct."Invalid userid." if the userid is non-existent. |
| editsettings | {"token": string, "id": number, "style": number, "enter": number "sound": number, "total": number} |
{"error": string} | Changes the internal settings for the user with the given userid. The token either needs to be for this user, or a user who is an admin. | "Style is invalid." if the style is not within 1 to 10."Enter-setting is invalid." if the enter setting is not 0 or 1."Sound-setting is invalid." if the sound setting is not 0 or 1."Total-setting is invalid." if the total setting is not within 1 to 50."Invalid userid." if the userid is non-existent. |
| editstate | {"token": string, "id": number, "state": number} |
{"error": string} | Changes the state for the user with the given userid. The token needs to be for an admin. | "Invalid state." if the state is not -1, 0 or 1."Invalid userid." if the userid is non-existent. |
| editusername | {"token": string, "id": number, "username": string} |
{"error": string} | Changes the username for the user with the given userid. The token needs to be for an admin. | "Username too long or empty." if the username is empty or more than 50 characters."Invalid userid." if the userid is non-existent. |
| getid | {"token": string} | {"error": string, "id": number} |
Gets the userid for the user associated with the given token. | None |
| getonline | {"token": string} | {"error": string, "online": [ {"id": number, "username": string} ]} |
Gets the online users, that is, the users that have made requests in the last 15 seconds. Note that clients using the websocket-api might appear offline, due to only making request when updates happen. | None |
| getonline2 | {"token": string} | {"error": string, "online": [ {"id": number, "username": string} ]} |
Also gets gets the online users, in this case the users who have active websocket-connections. | None |
| getuser | {"token": string, "id": number} |
{"error": string, "id": number, "username": string, "state": number, "display": { "color": string, "nick": string, "image": string }, "settings": { "style": number, "enter": number, "sound": number, "total": number }} |
Gets the userdata for a given userid. The token either needs to be for this user, or a user who is an admin. | "Invalid userid." if the userid is non-existent. |
| getusers | {"token": string} | {"error": string, "users": [ {"id": number, "username": string} ]} |
Gets a list of all users. The token needs to be for an admin. | None |
/elzchat6/api/chat.php is responsible for messages in the chat.
It handles getting messages, placing them and other chat-related things. Making backups is also handled here.
The userid given in the message data can, besides being a valid user, be 0 or -1.
A userid of 0 means that the message is a 'important message' (has a different color, no associated user),
and because of that, the username and display data given are default values and are unneeded.
A userid of -1 means that the message is from a deleted user,
and the username and display data are default values.
The postdate parameter gives a printable date, while the time paramter gives a unix timestamp.
| type | data | returned data | explanation | non-general errors |
|---|---|---|---|---|
| clearchat | {"token": string} | {"error": string} | Clears all chat messages. The token needs to be for an admin. | None |
| createbackup | {"token": string} | {"error": string} | Creates a backup of the full ElzChat state (chat, users, ElzPlace). These backups are not available via the API. The token needs to be for an admin. | None |
| deletemessage | {"token": string, "id": number} |
{"error": string} | Deletes the message with the given id. The token must be for the user who originally posted the message, or an admin. The token must not be for a banned user. | "Invalid message id." if the message id does not exist. |
| editmessage | {"token": string, "id": number, "message": string} |
{"error": string} | Edits the message with the given id. The token must be for the user who originally posted the message, or an admin. The token must not be for a banned user. | "Message too long or empty." if the message is empty or more than 1024 characters."Invalid message id." if the message id does not exist. |
| getmessage | {"token": string, "id": number} |
{"error": string, "userid": number, "id": number, "time": number, "message": string, "postdate": string, "username": string, "state": number, "display": { "color": string, "nick": string, "image": string }} |
Gets the message contents and data from the message with the given id. | "Invalid message id." if the message id does not exist. |
| getmessages | {"token": string, "start": number, "amount": number} |
{"error": string, "total": number, "messages": [ {"userid": number, "id": number, "time": number, "message": string, "postdate": string, "username": string, "state": number, "display": { "color": string, "nick": string, "image": string }} ]} |
Gets the given amount of messages starting at the given start value, sorted by date, newest to oldest. Also gives the total amount of messages in the chat. If the start value is 0, it is always deemed valid. When the start value lies close to the total messages, less messages than the amount value might be returned. | "Invalid start value." if the start is negative or above the total amount of messages."Invalid amount value." if the amount is not within 1 to 50. |
| postimportant | {"token": string, "message": string} |
{"error": string} | Places a important message. The token must be for an admin. | None |
| postmessage | {"token": string, "message": string} |
{"error": string} | Places a message. The token must not be for a banned user. | "Message too long or empty." if the message is empty or more than 1024 characters. |
/elzchat6/api/place.php is responsible for placing and getting pixels in ElzPlace.
The colors that map to the values used by ElzPlace are the following:
0: #fff, 1: #ddd, 2: #999, 3: #111, 4: #fad, 5: #f00, 6: #f90, 7: #b74
8: #ee0, 9: #7f4, 10: #0b0, 11: #0de, 12: #09d, 13: #30f, 14: #e5e, 15: #908.
| type | data | returned data | explanation | non-general errors |
|---|---|---|---|---|
| clearplace | {"token": string} | {"error": string} | Clears the pixels of ElzPlace back to color 0. The token must be for an admin. | None |
| getpixels | {"token": string} | {"error": string, data: [ [number] ]} |
Gets the pixel data for ElzPlace, as an array of 250 arrays with 250 numbers each. Each number-array represents a row, each inner number a pixel of that row, top-to-bottom, left-to-right. | None |
| placepixel | {"token": string, x: number, y: number, color: number} |
{"error": string} | Places a pixel at (x,y) with the given color. The token must not be for a banned user. | "Invalid x position." if the x position is not in range 0 to 249."Invalid y position." if the y position is not in range 0 to 249."Invalid color." if the color is not in range 0 to 15. |
The websocket-API is available at wss://elzod.ovh/ws/elzchat and provided messages about updates to the chat, online users and ElzPlace.
After connecting, send a single message as stringified JSON containing the token for the user, formed as {"token": string}.
When this is done, stringified JSON messages will be recieved formed as {"updated": number}.
The number will be 0 if the chat has updated, 1 if the online users (based on websocket-connections) updated and 2 is ElzPlace updated.
After recieving such an update, make appropiate API-requests to fetch the new state.
Additionally, a message containing {"ping": true} will be send every so often, which should be responded to with {"pong": true}.
The messages in ElzChat can contain markup and URL's.
The first thing done is detecting URL's. These are checked as follows:
If a word (string seperated by spaces, newlines or tabs) start with a \,
the URL is escaped and will not be detected.
If it starts with http:// or https:// it is seen a a URL.
If it contains a dot, does not end in a number or dot and does not start with a dot, it is seen as a URL.
Else, it is considered not a URL. If a URL didn't start with http:// or https://,
it is included in the target of the URL.
URL's are not parsed for other markup.
Markup is activated by certain characters. They can be escape with \.
If a \ appears without escaping markup, it is included litterally.
\ itself can aso be escaped with another \.
The following characters affect the inline markup:
*, meaning bold,
^, meaning underlined,
_, meaning italic,
~, meaning striped through and
`, meaning monospaced.
Finding one of these characters toggles the markup on or off.
Having an uneven number of characters will affect the message to the end.
Block-markup starts with # and ends with $,
and can also be escaped with \.
A block is a marked part of a message. They can apper within themselves
and are used for the quote feature of ElzChat.
Starting or ending a block also toggles all inline markup to off.
All blocks are closed at the end of the message.
Finding a $ while no block is open makes it appear in the message litterally.
ElzChat 6 changelog (API changes in blue italics):
9 Feb 2018 - 6.0b1:
recoded everything, created API
re-added base functionality (logging in/out and placing/viewing messages)
added page system
added online user-viewer
10 Feb 2018 - 6.0b2:
added id to chat.php API
fixed logout button
fixed layout
fixed special characters in messages breaking the chat
re-added logged-in user information
10 Feb 2018 - 6.0b3:
changed timeout to 15 seconds
re-added enter-to-send
re-added editing
re-added deletion
re-added important message sending
re-added chat clearing
re-added message counter
10 Feb 2018 - 6.0b4:
added total setting to user.php API
added time to chat.php API
fixed bug where initial settings were invalid
fixed bug where not all text was broken correctly
added delete-confirmation
re-added settings
re-added state editing (banning/unbanning and changing to/from admin)
added settings viewing
added user deletion
added password editing
re-added sound
re-added message preview
re-added styles
11 Feb 2018 - 6.0b5:
fixed editing-layout bugs on mobile devices
fixed cookies not working in Internet Explorer
improved feedback when editing
added page selector to bottom of page
re-added enter support
re-added markup
re-added markup escaping
added URL-markup
15 Feb 2018 - 6.0b6:
fixed bug where failed requests were not always catched
fixed margins being too small
re-added URL-detection
removed URL-markup in favor of URL-detection
changed block markup
replaced markup-parser with new version
re-added title-notfications
re-added browser-notifications
re-added quotes
15 Feb 2018 - 6.0b7:
re-added ElzPlace
re-added links to project page and API
11 Mar 2018 - 6.0b8:
fixed banned users being able to edit or delete messages
replaced message-sound with quieter version
re-added color-sliders
improved settings-interface
fixed bug where pressing enter re-enabled the post button when banned
fixed delete button not properly being styled after a failed deletion
13 Mar 2018 - 6.0b9:
fixed banned users being able to edit their display-settings
fixed a critical error where deleted-user messages could be assosiated with newly created users
fixed slider-text being too small in the 'Undertale'-style
9 Jul 2018 - 6.0b10:
fixed users being unable to delete themselfes
added 'delete account' function to settings
added support for logging in or registering by pressing enter
10 Jul 2018 - 6.0:
pushed ElzChat out of beta
25 Sep 2019 - 6.1:
Removed "No database connection." and "Failed to execute query." errors as being possible
Added "Wrong content-type." error when the content-type is not correct
Removed "Place-data is corrupt." error from place.php API
Fixed possible flashes when changing the color sliders in settings
Fixed register-button not being re-enabled when passwords don't match
Attempted fix for Safari giving the 'Notifications enabled'-notification on each visit
Fixed escaping markup not working at the start of messages or after spaces
Removed double-backslash to not escape backslashes in URLs and slightly modified URL-detection
Password edit-box now closes when password was succesfully changed
24 Nov 2020 - 6.2:
Removed "Wrong method." error as being possible, returning a 404 instead
Updated ElzPlace to be 250 by 250 pixels in size
Fixed documentation of URL detection
The edit-field now allows enter-to-edit and gets auto-focussed
Decreased update-rate for ElzPlace and improved scaling method
Zoom button in ElzPlace is now disabled when not clickable
29 May 2021 - 6.3:
Added "createbackup" to chat.php API
Terms & conditions and privacy policy are now avaliable when registering
Added support for clearing ElzPlace and making backups in the admin-UI
19 Dec 2021 - 6.4:
Added "getonline2" to user.php API
Added websocket-API
Chat and ElzPlace now makes use of the websocket-API
Online users are now based on websocket-connections
25 Dec 2021 - 6.5:
Added pinging to the websocket-API
Reconnection attempts will now happen if the websocket-connection closed
Updates that were missed due to the connection being closed will now occur upon reconnection
Fixed the connection closing when idling for too long
Sound playback for new messages has been improved
Buttons in ElzPlace now have a border for improved visibility