docs/helpserv.txt

   1 How HelpServ Works
   2 ------------------
   3
   4 HelpServ is a bot designed to help with queues of questions (or
   5 support requests).  It's designed to work well in multiple channels
   6 at once.
   7
   8 There is a one-to-one mapping between help bots and channels they act
   9 in; this is to allow privmsgs to work without having users specify a
  10 channel (which is much easier to use).  For example, HelpServ might be
  11 in #support, and Interview could be in #counterstrike; both would be
  12 bots of this kind, but they would have totally separate user lists and
  13 data sets.
  14
  15 Each channel/help bot has a set of "helper" users, defined by the
  16 channel admin(s).  In the rest of this document, I will use "helper"
  17 to indicate someone on the helper list for the channel, and "user" to
  18 indicate all other users.  There are also "manager" users and one
  19 "owner" for the bot.
  20
  21 There are two primary modes: "command mode" and "help mode."  Helpers
  22 default to command mode, and other users default to help mode.
  23 Command mode uses a command parser similar to the standard services.
  24 Help mode queues each user's messages into a virtual folder for later
  25 perusal by a helper.  A helper who is actively using "help mode" may
  26 issue "command mode" lines by prefixing them with a "command word" for
  27 the channel.
  28
  29 In Help Mode
  30 ------------
  31
  32 When a normal user joins the channel, a customizable greeting is sent.
  33 This usually tells the user to privmsg the bot for help (or to queue a
  34 question).  It is recommended that this include a URL to a FAQ.  The
  35 bot then shuts up until the user msgs them again.
  36
  37 When a user msgs the bot for the first time after they join, it opens
  38 a virtual folder for them.  The time of this request is filed, and
  39 they are added to a queue.  It also sends another customizable
  40 message.  The virtual folder is kept active until a helper closes it
  41 or the user is "lost"; when the virtual folder is closed, it is
  42 written out to a file (with statistics on when it was opened, closed,
  43 if (and when) it was picked up by a helper, etc).
  44
  45 A user is "lost" when:
  46  - For QUIT-based requests (or queues), the user disconnects from IRC.
  47  - For PART-based requests, the user parts the channel.
  48  - For handle-based requests, the handle is unregistered.
  49 The "default" mode for queues is close-based -- which behaves as
  50 handle-based if the user is authed and quit-based otherwise.
  51
  52 Helpers may also annotate an existing request, using the NOTE command.
  53
  54 In Command Mode
  55 ---------------
  56
  57 The following commands are defined:
  58
  59 LIST - show the currently open requests (unassigned first, then
  60   assigned)
  61
  62 NEXT - acts as PICKUP for the next unassigned request
  63
  64 PICKUP <reqno> - assign request number to self
  65
  66 REASSIGN <reqno> <helpernick|*handle> - reassign request to another
  67   (online) helper
  68
  69 CLOSE <reqno> <comment> - close request, with comment
  70 CLOSELAST <comment>     - close last PICKUP'ed or HANDOFF'ed request
  71
  72 NOTE [<reqno>] <comment> - add a note to a request (if not a number, use last assigned)
  73
  74 TOGMODE - switch between command mode and help mode
  75
  76 IGNORE <handle>         - Ignore the specified handle (or hostmask)
  77 IGNORE <nick!user@host> - in the future.  Does not close current requests.
  78
  79 ADDMANAGER <nick|*handle> - add or remove a manager or helper
  80 DELMANAGER <nick|*handle>   (managers may add and remove users
  81 ADDHELPER <nick|*handle>    and see statistics for anyone)
  82 DELHELPER <nick|*handle>
  83
  84 PAGE [<explanation>] - send a page, if enabled
  85
  86 SET [<option> <value>] - set an option:
  87   - GREETING - message sent when user joins channel
  88   - OPENREQ - message sent when user opens a request
  89   - CLOSEREQ - message sent to requester when a request is closed
  90   - CMDWORD - "command mode" escape word (for helpers in help mode)
  91   - PAGEDEST - target for pages
  92   - PAGEMSG - default page text (if no explanation when PAGE invoked)
  93   - IDLETIME - how long (with users, not helpers in the channel) before
  94                bot complains to PAGEDEST
  95   - WHINETIME - how long before an unhandled request will make the bot
  96                 complain to PAGEDEST
  97   - WHINEINTERVAL - how frequently the bot will complain about unhandled
  98                     requests, or users in channel without heleprs there
  99   - REASSIGN - privileges to use REASSIGN (helper, manager, owner)
 100
 101 STATS [<nick|*handle>] - show statistics for nick/handle (must be self,
 102                          or self must be a manager; defaults to self)
 103
 104 STATSREPORT - show overall statistics (such as?)
 105
 106 Statistics
 107 ----------
 108
 109 For any helper (includes managers), the following statistics are kept:
 110
 111 - Time in channel (total, this week, this month)
 112 - Requests "picked up"
 113 - Requests closed
 114 - Requests handed off
 115 - Handoffs received