chat/README.chatbot-api

   1 The 'chatbot' API
   2 -----------------
   3
   4 The chatbot API allows chatbots to interact in chatrooms as if they
   5 were ordinary users. Potentially it could also be used in the future
   6 to allow Java applets on the client to post and read messages.
   7
   8 Chatbots are designed to be written in a scripting language such as
   9 perl with libwww-perl. The API has been designed so that the scripting
  10 language doesn't necessarily have to be multi-threaded (to deal with
  11 multiple chatrooms), although you could use a threaded language if
  12 you wanted to.
  13
  14 Another concern is that the API has been designed so that it shouldn't
  15 drop messages, except under abnormally huge loads.
  16
  17 The API consists of a single shared object script, normally located at
  18 http://server/so-bin/chatbot.so
  19
  20 The 'fn' parameter controls the function requested. This parameter is
  21 mandatory, and the possible values are explained below.
  22
  23 Room and message identification
  24 -------------------------------
  25
  26 Each room has a unique resource ID (resid).
  27
  28 Each message in a room has a unique message ID. At a particular point
  29 in time, a room contains a window of continuous message IDs:
  30
  31   room contains: [ first_message  . . . . . . . . last_message ]
  32
  33 The last_message is the most recently posted message.
  34
  35 The first_message ID is retrieved when you list all rooms (see
  36 fn=rooms below). You can then retrieve this message using the fn=wait
  37 function. To retrieve the next message, increment the message ID and
  38 call fn=wait again, and so on until you reach the last message. At
  39 this point, incrementing the message ID to last_message+1 and calling
  40 fn=wait causes the CGI call to wait until another message is posted.
  41
  42 As you will see below, fn=wait also allows you to retrieve messages
  43 across many different rooms.
  44
  45 Authentication
  46 --------------
  47
  48 Chatbots should send an authentication cookie. Currently, because of
  49 the no-security implementation (see below), they should send the
  50 following cookie:
  51
  52 name: userid
  53 value: chatbot's userid
  54
  55 Currently if no cookie is sent, the chatbot appears as an anonymous
  56 user. In future we will be adding proper, secure cookies and an
  57 authentication mechanism.
  58
  59 Error handling
  60 --------------
  61
  62 Error handling is through the normal HTTP mechanism so if you, for
  63 example, request a room which doesn't exist, then you will get a 500
  64 Internal Server Error, with an attached text/plain content section
  65 containing the error message.
  66
  67 Security
  68 --------
  69
  70 There is no security in the chat server at the present time.
  71
  72 API functions
  73 -------------
  74
  75 fn=rooms
  76 --------
  77
  78 Returns a list of the rooms available, one per line, in the following
  79 format:
  80
  81 resid msgid name_of_the_room
  82
  83 resid : the room resource ID (ie. unique number)
  84 msgid : the message ID of the first available message in the room
  85
  86 fn=wait
  87 -------
  88
  89 In its simplest form, this function allows you to retrieve messages
  90 posted in a room, possibly waiting for a message to be posted.
  91
  92 If the room has resid 1, and the first message ID (from the fn=rooms
  93 call) is 3, then calling:
  94
  95 fn=wait&rooms=1&msgids=1:3
  96
  97 reads message ID 3 from resid 1. To read the next message, increment
  98 the message ID, thus:
  99
 100 fn=wait&rooms=1&msgids=1:4
 101 fn=wait&rooms=1&msgids=1:5
 102 etc.
 103
 104 Eventually one of these calls will block until a message is posted
 105 in the room.
 106
 107 More normally, you will use the fn=wait call to monitor several rooms
 108 at once. For this, you need to construct:
 109
 110 rooms  : comma-separated list of resids
 111 msgids : comma-separated list of resid:msgid pairs
 112
 113 Each resid:msgid pair is the next expected message ID in each room.
 114 You should start with the first message ID from each room, and
 115 increment the msgid _only_ when you receive that msgid in that room.
 116 For example:
 117
 118 fn=wait&rooms=1,2&msgids=1:5,2:1
 119
 120 This API call may return one or more messages. Each message is on its
 121 own line with the following format:
 122
 123 resid msgid msgtype [optional fields depending on msgtype ...]
 124
 125 resid   : the room ID
 126 msgid   : the message ID
 127 msgtype : one of the following message types:
 128
 129 msgtype 'posted' (an ordinary posted message):
 130
 131   resid msgid posted hh:mm userid [username] text_of_the_message
 132
 133   hh:mm    : the time the message was posted
 134   userid   : the user ID (0 = the anonymous user)
 135   username : for non-anonymous users, the name of the user
 136   text_of_the_message : the message text as typed by the user
 137
 138 msgtype 'enter'/'leave' (a user entered or left the room):
 139
 140   resid msgid enter userid [username]
 141
 142   userid   : the user ID (0 = the anonymous user)
 143   username : for non-anonymous users, the name of the user
 144
 145 msgtype 'blank'/'gone': clients should ignore all messages of these types.
 146
 147 For example:
 148
 149 1 5 posting 10:45 2 rich This is a really insightful comment
 150 1 6 posting 10:46 0 This is an anonymous posting
 151 1 7 enter 3 bob
 152 1 8 leave 0
 153 2 1 blank
 154
 155 Chatbots should ignore lines that they don't understand (eg. if the
 156 line doesn't start with a number).
 157
 158 fn=post
 159 -------
 160
 161 Post a message to a room. The following parameters are required:
 162
 163 fn=post&room=resid&text=message
 164
 165 resid : the room ID
 166 text  : the text of the message in smart-text format
 167
 168 Note that chatbots reads back their own messages.