

#==========================================================

What is Shady Dial ?

Shady Dial is a predictive dialer for the Asterisk telephony
system.  It consists of some modifications to the C code
core of Asterisk, as well as control code written in Tcl.

PostgreSQL is used heavily.  In order to determine call
placement pacing, CDR logging to PostgreSQL is required.
PostgreSQL is also used to keep track of Agents, results of
phone calls, the phonebook to call, and more.


#==========================================================

What do I need to run Shady Dial ?

* A working Asterisk installation.  http://www.asterisk.org
* A PostgreSQL database backend.  http://www.postgresql.org
* Tcl version 8.3+.  http://www.tcl.tk/
* The Extended Tcl Package, TclX.  http://tclx.sourceforge.net/


#==========================================================

What has Shady Dial been successfully run on ?

A Pentium-4 2.4Ghz machine, with Debian Linux and Asterisk
from CVS.  Connected to a T1 and Zhone channel bank with a
Digium Wildcard T400P 4-port PCI card.  Standard analog
phones or headsets.


#==========================================================

What is the license for Shady Dial ?

Everything is covered by the GPL, except for pgin.tcl, which
is authored by L.J. Bayuk and is covered under a BSD
license.


#==========================================================

What files do I need to modify to get it to work ?

* In /etc/asterisk/agents.conf, you need to add a [global]
  section, to specify the PostgreSQL connection info.

  Example (above the [agents] portion):

  [global]
  connection=host=HOSTNAME dbname=DBNAME user=USERNAME password=PASSWORD
  resulttable=tbl_ast_agent_results
  agentview=vw_ast_agents

* In /etc/asterisk/queues.conf, you need to add each agent
  who will be using the dialer in the [slimagentq] queue.
  (Note this will be fixed once dynamic addition of Agents
  to Queues is implemented in Shady Dial).

  Example:

  [general]
  [slimagentq]
  timeout = 0
  retry = 0
  maxlen = 1
  strategy = leastrecent
  member => Agent/1
  member => Agent/2
  member => Agent/3
  member => Agent/4

* In /etc/asterisk/extensions.conf, you need to add a
  context for [shadydial] and [slimagent].

  Example:

  [shadydial]

  exten => s,1,Queue,slimagentq
  exten => 100,1,Queue,slimagentq
  exten => i,1,Hangup

  [slimagent]

  exten => s,1,AgentLogin
  exten => 100,1,AgentLogin
  exten => i,1,Hangup

* In /etc/asterisk/manager.conf, you need to add an entry
  for the manager who will be connecting to Asterisk via the
  Tcl-manager interface provided in astman.tcl

* In the shadydial.tcl source, you need to edit the connection
  parameters for both the PostgreSQL database and the
  Asterisk manager interface.

* Add a line to your crontab to "kick the dialler".  This is
  lame, but it keeps the connection alive if Asterisk dies.

  */1 * * * *     root    tclsh /usr/local/bin/kickthedial.tcl


#==========================================================

Where do I put the source files for Shady Dial ?

app_queue.c should replace apps/app_queue.c in the Asterisk
source.  chan_agent.c should replace channels/chan_agent.c
in the Asterisk source.  All the Tcl files should be put
into /usr/local/bin and made executable.


#==========================================================

What sound samples do I need to record ?

You need to record the following into /var/lib/asterisk/sounds
You can use the Record application that comes with Asterisk.

slimagent-welcome:  Announces entrance to Shady Dial, asks
                    Slim Agent to enter their Agent ID.
slimagent-loginok:  Congratulations you logged in.
slimagent-pass:     Optional, if your Agents have passwords.
                    (You'll then also need
                    slimagent-incorrect)
slimagent-result:   Simply "result" should work, this file is
                    played at the end of a phone call before
                    the user enters a result code.
slimagent-thankyou: Pretty much just a thank you.
slimagent-repeat:   Played before the phone number is
                    repeated back for a 2nd time at the end
                    of the call.


#==========================================================

What stuff do I have to put in the PostgreSQL database ?

You need to create 4 tables, 4 views, and 2 functions.  SQL
to create them is in the, get this, SQL file accompanying
Shady Dial (except the vw_ast_agents View.)  The functions
are written in plpgsql, so you need to use the PostgreSQL
'createlang' program to allow for them to be created.

shadydial_phonebook:        Table accessed by Tcl code to
                            originate calls.
                            Needs: SELECT, UPDATE for user
shadydial_results:          Table with all possible result
                            codes, currently 0-9 or so, accessed
                            by Tcl code.
                            Needs: SELECT for user
tbl_ast_agent_results:      Table that holds results for each
                            call, accessed by chan_agent in *.
                            Needs: INSERT for user
shadydial_speed:            Table to hold the boss adjusted
                            speed.
                            Needs: SELECT for user
vw_ast_agents:              View accessed by chan_agent that
                            shows valid agents.
                            Needs: SELECT for user
                            NOTE that this view should be
                            based on a table that you are
                            using to keep track of your
                            agents elsewhere with, for
                            example, payroll.  The View just
                            needs to return strings like:
                                1,546,Chip Munk
                                2,324,Dale Ranger
                                3,,Jean Chretien
                            so that's:
                                worker_id,password(optional),name
                            and the column name is 'agent'
vw_shadydial_bunch_o_nums:  View that spits out a bunch of
                            numbers to call, used by Tcl
                            code.
                            Needs: SELECT for user
vw_shadydial_results:       Just a view over the
                            shadydial_results table.
                            Needs: SELECT for user
vw_cdr_pace:                View of the CDR logging to help
                            in call placement timing.
                            Needs: SELECT for user
shadydial_get_call_pace():  Function to regulate call
                            placement rate.
                            Needs: EXECUTE for user
shadydial_get_speed():      Function to get user defined
                            'speed', so the boss can change
                            it if it is not fast enough.
                            Needs: EXECUTE for user

Create the datbase like so:

    $ createdb mydialer

Create the language for the functions like so:

    $ createlang plpgsql mydialer

Cram the SQL file into your database like so:

    $ psql mydatabase < SQL

You will need to create a user, say, callerperson, and grant
them privileges as specified in the above Needs: lines.


#==========================================================

How does a caller use the system ?

Assuming you've gotten everything else setup, the
shadydial_phonebook table is full of numbers to call, all
views created, etc., then the process is pretty hands off.

An agent/caller picks up and dials the extension for the
AgentLogin application (as shown in the [slimagent] context
above.  They enter their Agent ID and press pound.  After
they get an okay voice message from the system, they start
hearing hold music.

Meanwhile, the program is checking to see who is logged in,
if there is anyone waiting, etc., and starts making calls as
deemed necessary.  When a call is connected, the Agent hears
a 'beep' and the first 'hello' out of the person on the
other end of the line.

Parties proceed to talk about the weather, and the Agent can
hang up by hitting * or gets disconnect when the other end
hangs up.  A voice prompt will ask for a result code, so the
Agent punches in a code from the shadydial_results table
then hits pound.

If the result was 5, the code for a 'sale', then the agent
will hear the phone number repeated to them twice.  If it is
any other code, they simply get back in line for the next
call instead of hearing the phone number first.  The process
then continues as long as the Agent stays logged in.


