The 'chatbot' API ----------------- The chatbot API allows chatbots to interact in chatrooms as if they were ordinary users. Potentially it could also be used in the future to allow Java applets on the client to post and read messages. Chatbots are designed to be written in a scripting language such as perl with libwww-perl. The API has been designed so that the scripting language doesn't necessarily have to be multi-threaded (to deal with multiple chatrooms), although you could use a threaded language if you wanted to. Another concern is that the API has been designed so that it shouldn't drop messages, except under abnormally huge loads. The API consists of a single shared object script, normally located at http://server/so-bin/chatbot.so The 'fn' parameter controls the function requested. This parameter is mandatory, and the possible values are explained below. Room and message identification ------------------------------- Each room has a unique resource ID (resid). Each message in a room has a unique message ID. At a particular point in time, a room contains a window of continuous message IDs: room contains: [ first_message . . . . . . . . last_message ] The last_message is the most recently posted message. The first_message ID is retrieved when you list all rooms (see fn=rooms below). You can then retrieve this message using the fn=wait function. To retrieve the next message, increment the message ID and call fn=wait again, and so on until you reach the last message. At this point, incrementing the message ID to last_message+1 and calling fn=wait causes the CGI call to wait until another message is posted. As you will see below, fn=wait also allows you to retrieve messages across many different rooms. Authentication -------------- Chatbots should send an authentication cookie. Currently, because of the no-security implementation (see below), they should send the following cookie: name: userid value: chatbot's userid Currently if no cookie is sent, the chatbot appears as an anonymous user. In future we will be adding proper, secure cookies and an authentication mechanism. Error handling -------------- Error handling is through the normal HTTP mechanism so if you, for example, request a room which doesn't exist, then you will get a 500 Internal Server Error, with an attached text/plain content section containing the error message. Security -------- There is no security in the chat server at the present time. API functions ------------- fn=rooms -------- Returns a list of the rooms available, one per line, in the following format: resid msgid name_of_the_room resid : the room resource ID (ie. unique number) msgid : the message ID of the first available message in the room fn=wait ------- In its simplest form, this function allows you to retrieve messages posted in a room, possibly waiting for a message to be posted. If the room has resid 1, and the first message ID (from the fn=rooms call) is 3, then calling: fn=wait&rooms=1&msgids=1:3 reads message ID 3 from resid 1. To read the next message, increment the message ID, thus: fn=wait&rooms=1&msgids=1:4 fn=wait&rooms=1&msgids=1:5 etc. Eventually one of these calls will block until a message is posted in the room. More normally, you will use the fn=wait call to monitor several rooms at once. For this, you need to construct: rooms : comma-separated list of resids msgids : comma-separated list of resid:msgid pairs Each resid:msgid pair is the next expected message ID in each room. You should start with the first message ID from each room, and increment the msgid _only_ when you receive that msgid in that room. For example: fn=wait&rooms=1,2&msgids=1:5,2:1 This API call may return one or more messages. Each message is on its own line with the following format: resid msgid msgtype [optional fields depending on msgtype ...] resid : the room ID msgid : the message ID msgtype : one of the following message types: msgtype 'posted' (an ordinary posted message): resid msgid posted hh:mm userid [username] text_of_the_message hh:mm : the time the message was posted userid : the user ID (0 = the anonymous user) username : for non-anonymous users, the name of the user text_of_the_message : the message text as typed by the user msgtype 'enter'/'leave' (a user entered or left the room): resid msgid enter userid [username] userid : the user ID (0 = the anonymous user) username : for non-anonymous users, the name of the user msgtype 'blank'/'gone': clients should ignore all messages of these types. For example: 1 5 posting 10:45 2 rich This is a really insightful comment 1 6 posting 10:46 0 This is an anonymous posting 1 7 enter 3 bob 1 8 leave 0 2 1 blank Chatbots should ignore lines that they don't understand (eg. if the line doesn't start with a number). fn=post ------- Post a message to a room. The following parameters are required: fn=post&room=resid&text=message resid : the room ID text : the text of the message in smart-text format Note that chatbots reads back their own messages.