autoattendant.lua

(C)opyright 2008 by R. Marc Lewis <marc@avvatel.com>
gottafixthat on #freeswitch

This file is contributed to the FreeSWITCH project and licenced under
the Mozilla Public License v1.1

This is a simple script that allows auto attendants (IVR's) to be
created dynamically from the XML dialplan.  It was designed to work with
mod_xml_curl in a multi-tennant installation.  I'll try to work up
better documentation for this is time goes on, but it is a fairly simple
script (less than 200 lines as of right now) and should be fairly easy
to follow.

To call the auto attendant (AA), you set variables in your XML dialplan.  All
of the auto attendant variables are prefixed by 'aa' so they should not
collide with any other system variables.

The AA can handle the following actions:

  hangup:  Self explanatory
  autoattendant:  Jump to another auto attendant (see below)
  repeat:  Repeat the current auto attendant
  prefix:  Extension Prefix Dialing, i.e. User dials "1", get another
           'n' digits and then transfer to that extension.
  exten:  Transfer to an extension
  voicemail:  Transfer to voicemail
  dialbyname:  Dial by name directory.  Not implemented yet, coming soon.

Setup variables are:

  aa_domain:  The SIP domain to use, if not set defaults to the system
              domain.
  aa_announcement:  The sound file to play when the AA starts.
  aa_timeout:  The number of seconds to wait for a digit, if not set it
               defaults to 30 seconds.
  aa_timeoutaction:  The action to take if the caller doesn't enter a
                     digit within the specified amount of time.  If not
                     set, this defaults to 'hangup'
  aa_timeouttarget:  The target for the timeout action, i.e. the
                     extension number to transfer to, the mailbox, etc.
  aa_invoptannounce:  The sound file to play when the user selects
                      an invalid option.
  aa_invoptaction:  The action to take when the user selects an invalid
                    option, defaults to 'hangup'.
  aa_invopttarget:  The target for the invalid option action.
  aaDigitAct[0-9,star,pound]: The DTMF keys, i.e. aaDigit0 or aaDigitstar,
                              the action to take.
  aaDigitPlay[0-9,star,pound]:  The sound file to play back when the
                                caller dials this key.
  aaDigitTarget[0-9,star,pound]:  The sound file to play back when the
                                caller dials this key.
  
A fully working example:

<extension name="200-cheetahis">
   <condition field="destination_number" expression="^200$">
      <action application="answer"/>
      <action application="sleep" data="750"/>
      <action application="set" data="aa_domain=cheetahis.cisvp.com"/>
      <action application="set" data="aa_timeout=20"/>
      <action application="set" data="aa_announcement=/shared/freeswitch/users/c/ch/cheetahis.cisvp.com/recordings/1000.wav"/>
      <action application="set" data="aa_timeoutaction=repeat"/>
      <action application="set" data="aa_timeouttarget="/>
      <action application="unset" data="aa_invoptannounce"/>
      <action application="set" data="aa_invoptaction=repeat"/>
      <action application="set" data="aa_invopttarget="/>
      <action application="set" data="aaDigitAct1=prefix"/>
      <action application="set" data="aaDigitPlay1="/>
      <action application="set" data="aaDigitAct2=exten"/>
      <action application="set" data="aaDigitTgt2=201"/>
      <action application="set" data="aaDigitPlay2="/>
      <action application="set" data="aaDigitAct3=exten"/>
      <action application="set" data="aaDigitTgt3=202"/>
      <action application="set" data="aaDigitPlay3="/>
      <action application="set" data="aaDigitAct4=exten"/>
      <action application="set" data="aaDigitTgt4=203"/>
      <action application="set" data="aaDigitPlay4="/>
      <action application="set" data="aaDigitAct8=voicemail"/>
      <action application="set" data="aaDigitTgt8=100"/>
      <action application="set" data="aaDigitPlay8="/>
      <action application="unset" data="aaDigitAct5"/>
      <action application="unset" data="aaDigitAct6"/>
      <action application="unset" data="aaDigitAct7"/>
      <action application="unset" data="aaDigitAct9"/>
      <action application="unset" data="aaDigitAct0"/>
      <action application="unset" data="aaDigitActpound"/>
      <action application="unset" data="aaDigitActstar"/>
      <action application="lua" data="autoattendant.lua"/>
      <action application="hangup"/>
   </condition>
</extension>

The 'unset' is necessary if calling other auto attendants during the
same session, since FreeSWITCH will maintain the variables.  Failing to
unset the variables may result in keys from the first auto attendant
being active in the second.

The only other special consideration is the regex used for jumping to
another auto attendant.  It expects there to be an extension that will
match 'aa-name', where 'name' is the name of the auto attendant we're
jumping to.