README

Support chat
============

Requirements
------------

Server:
- An XMPP server with support for:
 - Multi-User Conferences (may be an external service, e.g. mu-conference, Palaver)
 - BOSH (may be an external service, e.g. Punjab)
 - SASL ANONYMOUS

- A web server:
 - To serve the scripts, stylesheets and images
 - To redirect requests for a selected URL to the BOSH server

Users:
- A Javascript-enabled web browser

Installation
------------

Upload the 'support-chat' directory to your site. In the page(s) in
which you intend to enable the support box to be launched, add the
following snippet of HTML to the <head> section of the page:

       <script type="text/javascript" src="support-chat/js/jquery-1.4.2.min.js"></script>
       <script type="text/javascript" src="support-chat/js/strophe.js"></script>
       <script type="text/javascript" src="support-chat/js/xmpp_muc.js"></script>
       <script type="text/javascript" src="support-chat/js/supportchat.js"></script>
       <script type="text/javascript" src="support-chat/js/jquery-ui-1.8rc3.custom.min.js"></script>
       <link rel="stylesheet" href="support-chat/ui/supportchat.css" />
       <link rel="stylesheet" href="support-chat/ui/start/jquery-ui-1.8rc3.custom.css" />

(amending the paths as necessary to point to the correct files).

Configuration
-------------

On your XMPP server you need to create a new host for users to connect to. This host
should be configured to allow SASL ANONYMOUS logins. You also need to create a host
to hold the user-created support rooms using MUC. This will either be provided by 
your server, or by configuring an external component.

On your web server the only tricky part is setting up a proxy for the scripts on the
site to access the BOSH server. Apache, lighttpd, nginx and other servers support this.
There are many ways to achieve this, but one method in Apache2 would be to use its
mod_rewrite and a configuration line similar to:

       RewriteRule /bosh http://localhost:5280/http-bind/ [P]

This assumes your BOSH server is on the same machine as the web server, and is serving
BOSH at /http-bind (the default path in most servers). You should in the end be able
to visit http://yourdomain/bosh and see the BOSH page of your server.

Finally you need to configure and customise support-chat itself. Open up
support-chat/supportchat.js in an editor, and review and modify the configuration
options at the start of the file. Each one is described below:

login_domain: This should be the XMPP hostname that is configured to allow anonymous
              logins.

bosh_url:     This should be /bosh, or the path you proxied from your web server to
              the BOSH server.

muc_server:   The XMPP hostname of the Multi-User Conference server where users shall
              create their temporary rooms.

team_rooms:   A list of pairs of assistant team names and team MUC addresses. The
              example should give you enough guidance on how to structure the list.
              You can define as many or as few teams as you want.

send_invites: May be true or false. If false, online assistants will receive messages
              alerting them to new queries. If true, they will receive a MUC invitation
              to the query's room (may not work in all XMPP clients).

offline_support: An XMPP address to which queries should be sent when no assistants on
              the selected team are available. Should have offline message storage
              in order to be sure never to lose a query.

alternative_url: If the support application encounters an issue connecting to the XMPP
              server (whether it be down, or the user's network policy or browser
              prevents such) the user will be directed to the given URL to obtain
              support.

Usage
-----
Anywhere you want to provide a link to open the support interface, direct the link to
#support-chat, for example:

        <a href="#support-chat">Live Support</a>

On clicking this link the user would be presented with a form to enter their query.

License
-------
support-chat is licensed under the University of Illinois/NCSA Open Source License,
see the LICENSE file that accompanies this project for more information.