Mercurial > support-chat / file revision

README@35a99353d907

README

Fri, 16 Apr 2010 18:51:44 +0100

author
matthew@heavyhorse.vm.bytemark.co.uk
date
Fri, 16 Apr 2010 18:51:44 +0100
changeset 60
35a99353d907
parent 49
6d46d2518705
permissions
-rw-r--r--

Add documentation to README for assistants

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.

Assistants
----------

To become available to answer user queries, assistants should join the relevant team
MUC room(s). When a user submits a query they will receive a message with the query
and the address of a room to join if they wish to assist the user.

The first assistant to join the room is automatically marked as the user's primary
assistant, and the user will be notified of their presence. They can simply converse
with the user as normal at this point.

While in the query room with the user present, 2 commands are available. Anyone may
type the message "!assist" to notify the user that they will be the new primary
assistant. If the assistant wishes to notify the user that they are no longer have an
assistant they may type the message "!stop", or simply leave the room.

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.

Mercurial Repository: support-chat

mercurial