root/HelpIM3_chi/protocol.txt

Protocol between HelpIM3 web application and the chatbot.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Chats between a client and a staffmember takes place in jabber MUC-rooms (Multi User Chat). The
reason for using MUC-rooms for (mainly) two-person chat sessions is that the persons don't need to
be in eachothers roster in order to be able to chat.

The main task of the jabber chatbot ("bot") is to create and manage the MUC-rooms on the jabber
server.  The web application ("webapp") is resonpsible for directing staff members and clients to
these MUC-rooms in order to start a private chat.

The bot and webapp negotiate room allocation and usage the following way:

  o   Reads configuration file with among other things:
      - Jabber-ID ("JID")
      - Nickname to use
      - Password
      - Jabber resource

  o   Create a pool of MUC-rooms:
      - Use unique name voor the MUC-rooms
      - Set a (random) password on the MUC-room
      - Make sure the is the owner of the rooms
      - Configures the rooms e.g. max number of chatters, backlog..
      - Make rooms available to the webapp by writing name-password combinations of the
        rooms into a database table

  o   When a staffmember is available for chat, the webapp takes a room from the database
      and directs the staffmember to one of the available rooms.

  o   When the bot sees the first person in a room it will be a staff member. The bot
      changes the status of the room in the database to confirm there is a
      staffmember in it available for chat.

  o   When the webapp has a client wishing to chat with a staff member, it puts the client
      into one of the rooms where a staffmember is available.
      (FIXME: is there an order of the rooms? E.g. the staffmember who is available for
      the longest time gets the next client to chat with?)

  o   When the bot sees a second person appear in the room it changes the status of the room
      to reflect that.

  o   The bot checks the number of active rooms and creates a new room if a certain maximum
      is not yet reached.

  o   When one of the chatters in a room leaves the room, the bot changes the status to
      reflect that fact.

  o   When the last chatter leaves the room the bot yet again changes the status of the room 
      in the database, and the bot also leaves the room, removing it from the jabber server.
      The closed room stays in the database for history record purposes.
      (FIXME: also record timestamps of statuschanges in the room?)

EOF