F-Chat Protocol

From F-List Wiki
Jump to: navigation, search

General Information

Introduction

About F-Chat

The F-Chat network is the first network of it's kind; a completely open online roleplaying chat network, that offers the freedom and support for third parties to implement their own client, as long as they properly follow the spec. F-Chat was developed as part of F-List.net, a large text-based roleplaying website, and community, by the request of it's users, who were asking for a way to roleplay in realtime, rather than post-by-post.

About this documentation

We aim to offer clear documentation to allow people to connect to F-Chat with third party clients. After all, the more people on our network, the more fun roleplaying will be! If you follow our guidelines and client implementation rules, we'll be happy to advertise your third party client and website as well.

Websockets

Connections are expected to follow WebSocket protocols, this means sending a valid Hybi WebSocket request header before sending commands.

All commands must be properly encapsulated in a valid Hybi WebSocket frame. Invalid WebSocket frames will result in a disconnect.

Connecting

The F-Chat server runs on chat.f-list.net:9722 (unencrypted) or chat.f-list.net:9799 (TLS). After connecting you cannot send commands, until you have properly identified, or you will be disconnected. A testserver for experimentation runs on port 8722 (unencrypted) or 8799 (TLS). Please use the test server for anything you are unsure of, testing on the live server is heavily discouraged. The web client may be made to connect to the test server to assist in development purposes by using the url of http://www.f-list.net/fchat/?useDev

Disconnecting

Simply closing the socket is acceptable. Server does not follow the websocket guidelines on closing sockets using the closing frame.

Command Format

All commands look like this:

XXX {"property":"value","anotherproperty":"value"}

Commands contain a three character message type. These currently are always capitalized, and are case-sensitive. This is followed by a space, and a json payload. All commands must be in valid UTF-8. Commands without a json payload should not contain a trailing space after the message type. The minimum size of a command is three characters. Commands under this size will result in a disconnect.

Error Codes

FChat error codes

Guidelines

Mandatory Client Requirements

On Connection to F-Chat, your client must uniquely identify itself as apart from an official client, and this includes both a client name and version.

Do not use official F-List images, sounds, and do not directly use the code official F-Chat clients use. The smiley set is an exception to this.

Your client must support and send text formatting as well-structured BBCode, and most not support BBCode tags which are not supported by official clients. In the same vein, the syntax for users to enter smilies and commands should be consistent or very similar to the syntax of official clients.

Your client must use server resources responsibly and intelligently; do not spam API requests, stagger re-connection attempts (with a reasonable time-out, 10 second minimum), do not spam commands to the server or willfully send garbage.

Your client must not store, transmit, upload, or otherwise tamper with or log with a user's information. Your client is allowed to log messages and commands received, but the location of these logs must be known and readily accessible to the user.

Your client should not crash upon receiving any command, even one it does not know. Unknown commands should be either logged for debugging or swallowed.

If possible, your client should implement rudimentary administration tools.

Bots

Bots are permitted! However, they must conform to the following rules:

  • Your bot must use server resources responsibly and intelligently: do not spam API requests, stagger re-connection attempts (with a reasonable time-out, 10 second minimum), do not spam commands to the server or wilfully send garbage.
  • Your bot should not enter rooms to which it has not been explicitly allowed by the channel owner. For public channels this means obtaining the permission of the global ops as a consensus through a ticket. The Development channel is an exception, although we do request that you mention you're testing a bot, if the bot is meant to respond to commands in the channel.
  • Your bot should not send PMs, friend requests, or channel invites to a user unless requested by the user through some user-initiated contact with the bot. (Like PMing the bot or using trigger commands in a channel.)
    • A private channel owner is allowed to have a single bot who sends a PM to any user who enters the channel; this is normally intended for bots that enforce channel-specific rules, so the bot can give users some explanation if it kicks them.
  • The character your bot operates on should contain a notice that the character is a chat bot, a brief summary of its intended purpose/functionality, and a name/link to the character who operates the bot on the profile page for the character.

Commands sent by the client

FChat client commands

Commands sent by the server

FChat server commands