Since all the modules require the neon library, we’ll install that first. Be sure to append .x86_64 to the end of the package name if installing on a 64-bit machine:

$ sudo yum install neon-devel

The next step is to install the libical-devel dependency. Unfortunately, this module is not shipped with CentOS and requires a third-party repository (see Third-Party Repositories). In this case, we need to install libical-devel from the EPEL (Extra Packages for Enterprise Linux) repository:

$ sudo yum --enablerepo=epel install libical-devel

After installing our dependencies, we can run the configure script in our Asterisk source directory and enable both the res_calendar and res_calendar_caldav modules from within the Resource Modules section of menuselect.

Because all the modules require the neon development library, we’re going to install that first. On Ubuntu, you will typically be given several different versions (e.g., on 10.04 we have the option of libneon 2.5, 2.6, and 2.7). We’re going to install the latest version available to us:

$ sudo apt-get install libneon27-dev

With libneon installed, we can now install the libical-dev package and its dependencies with apt-get:

$ sudo apt-get install libical-dev

After installing our dependencies, we can run the configure script in our Asterisk source directory and enable both the res_calendar and res_calendar_caldav modules from within the Resource Modules section of menuselect.

In our first example, we’re going to call a device and play back a reminder notice for a particular calendar event. It might be useful to get this type of reminder if you’re likely to be napping at your desk when your weekly Monday meeting rolls around. To set up a wakeup call reminder, we simply need to add the following lines to our calendar configuration in calendar.conf:

channel=SIP/0000FFFF0001
app=Playback
appdata=this-is-yr-wakeup-call

After making this change, reload the res_calendar.so module from the Asterisk console:

*CLI> module reload res_calendar.so

When the event rolls around, Asterisk will generate a call to you and play back the sound file this-is-yr-wakeup-call. The output on the console would look like this:

    -- Dialing SIP/0000FFFF0001 for notification on calendar myGoogleCal
  == Using SIP RTP CoS mark 5
    -- Called 0000FFFF0001
    -- SIP/0000FFFF0001-00000001 is ringing
    -- SIP/0000FFFF0001-00000001 connected line has changed, passing it to 
       Calendar/myGoogleCal-5fd3c52
    -- SIP/0000FFFF0001-00000001 answered Calendar/myGoogleCal-5fd3c52
    -- <SIP/0000FFFF0001-00000001> Playing 'this-is-yr-wakeup-call.ulaw' 
       (language 'en')

Remember that our refresh rate is set to 15 minutes and we’re gathering 60 minutes’ worth of events. You might have to adjust these numbers if you wish to test this out on your development server.

In this example we’re going to show how you can use a combination of some simple dialplan and the CALENDAR_EVENT() dialplan function to generate a call between two participants based on the information in the location field. We’re going to fill in the location field with 0000FFFF0002, which is the SIP device we wish to call after answering our reminder.

Add the following dialplan to your extensions.conf file:

[AutomatedMeetingSetup]
exten => start,1,Verbose(2,Triggering meeting setup for two participants)
   same => n,Set(DeviceToDial=${FILTER(0-9A-Za-z,${CALENDAR_EVENT(location)})})
   same => n,Dial(SIP/${DeviceToDial},30)
   same => n,Hangup()

When the event time arrives, our device will receive a call, and when that call is answered another call will be placed to the endpoint with which we wish to have our meeting. The console output looks like the following:

This is where our calendar triggers a call to our device

    -- Dialing SIP/0000FFFF0001 for notification on calendar myGoogleCal
  == Using SIP RTP CoS mark 5
    -- Called 0000FFFF0001
    -- SIP/0000FFFF0001-00000004 is ringing

And now we have answered the call from Asterisk triggered by an event

    -- SIP/0000FFFF0001-00000004 connected line has changed, passing it to 
       Calendar/myGoogleCal-347ec99
    -- SIP/0000FFFF0001-00000004 answered Calendar/myGoogleCal-347ec99

Upon answer, we trigger some dialplan that looks up the endpoint to call

    -- Executing [start@AutomatedMeetingSetup:1] Verbose("SIP/0000FFFF0001-00000004", 
       "2,Triggering meeting setup for two participants") in new stack
  == Triggering meeting setup for two participants


This is where we used CALENDAR_EVENT(location) to get the remote device

    -- Executing [start@AutomatedMeetingSetup:2] Set("SIP/0000FFFF0001-00000004", 
       "DeviceToDial=0000FFFF0002") in new stack

And now we're dialing that endpoint

    -- Executing [start@AutomatedMeetingSetup:3] Dial("SIP/0000FFFF0001-00000004", 
       "SIP/0000FFFF0002,30") in new stack
  == Using SIP RTP CoS mark 5
    -- Called 0000FFFF0002
    -- SIP/0000FFFF0002-00000005 is ringing

The other end answered the call, and Asterisk bridged us together

    -- SIP/0000FFFF0002-00000005 answered SIP/0000FFFF0001-00000004
    -- Locally bridging SIP/0000FFFF0001-00000004 and SIP/0000FFFF0002-00000005

Of course, the dialplan could be expanded to prompt the initial caller to acknowledge being ready for the meeting prior to calling the other party. Likewise, we could add some dialplan that plays a prompt to the other caller that lets her know that she has scheduled a meeting and that if she presses 1 she will be connected with the other party immediately. We could even have created a dialplan that would allow the original party to record a message to be played back to the other caller.

Just for fun, we’ll show you an example of the functionality we just described. Feel free to modify it to your heart’s content:

[AutomatedMeetingSetup]
exten => start,1,Verbose(2,Triggering meeting setup for two participants)

; *** This line should not have any line breaks
   same => n,Read(CheckMeetingAcceptance,to-confirm-wakeup&press-1&otherwise
&press-2,,1)

   same => n,GotoIf($["${CheckMeetingAcceptance}" != "1"]?hangup,1)

   same => n,Playback(silence/1&pls-rcrd-name-at-tone&and-prs-pound-whn-finished)

; We set a random number and assign it to the end of the recording
; so that we have a unique filename in case this is used by multiple
; people at the same time.
;
; We also prefix it with a double underscore because the channel
; variable also needs to be available to the channel we're going to call
;
   same => n,Set(__RandomNumber=${RAND()})
   same => n,Record(/tmp/meeting-invite-${RandomNumber}.ulaw)

   same => n,Set(DeviceToDial=${FILTER(0-9A-Za-z,${CALENDAR_EVENT(location)})})
   same => n,Dial(SIP/${DeviceToDial},30,M(CheckConfirm))
   same => n,Hangup()

exten => hangup,1,Verbose(2,Call was rejected)
   same => n,Playback(vm-goodbye)
   same => n,Hangup()

[macro-CheckConfirm]
exten => s,1,Verbose(2,Allowing called party to accept or reject)
   same => n,Playback(/tmp/meeting-invite-${RandomNumber})

; *** This line should not have any line breaks
   same => n,Read(CheckMeetingAcceptance,to-confirm-wakeup&press-1&otherwise
&press-2,,1)

   same => n,GotoIf($["${CheckMeetingAcceptance}" != "1"]?hangup,1)

exten => hangup,1,Verbose(2,Call was rejected by called party)
   same => n,Playback(vm-goodbye)
   same => n,Hangup()

We hope you’ll be able to use this simple dialplan example as a jumping-off point. With a little creativity and some dialplan skills, the possibilities are endless!

To expand upon the functionality in the previous section, we’re going to delve into the logic problem of how you might be able to place multiple participants into a meeting. Our goal is to use our calendar to call us when the meeting is scheduled to start, and then, when we answer, to place calls to all the other members of the conference. As the other participants answer their phones, they will be placed into a virtual conference room, where they will wait for the meeting organizer to join. After all participants have been dialed and answered (or perhaps not answered), the organizer will be placed into the call, at which point the meeting will start.

This type of functionality increases the likelihood that the meeting will start on time, and it means the meeting organizer doesn’t have to continually perform roll call as new participants continue to join after the call is supposed to start (which invariably happens, with people’s schedules typically being fairly busy).

The dialplan we’re going to show you isn’t necessarily a polished, production-ready installation (for example, the data returned from the calendar comes from the description field, only deals with device names, and assumes the technology is SIP). However, we’ve done the hard work for you by developing the Local channel usage, along with the M() flag (macro) usage with Dial(). With some testing and tweaks this code could certainly be developed more fully for your particular installation, but we’ve kept it general to allow for it to be usable for more people in more situations. The example dialplan looks like this:

[AutomatedMeetingSetup]
exten => start,1,Verbose(2,Calling multiple people and placing into a conference)

; Get information from calendar and save that information. Prefix
; CalLocation with an underscore so it is available to the Local
; channel (variable inheritance).
;
   same => n,Set(CalDescription=${CALENDAR_EVENT(description)})
   same => n,Set(_CalLocation=${CALENDAR_EVENT(location)})
   same => n,Set(X=1)

; Our separator is a caret (^), so the description should be in the
; format of:    0000FFFF0001^0000FFFF0002^etc...
;
   same => n,Set(EndPoint=${CUT(CalDescription,^,${X})})

; This loop is used to build the ${ToDial} variable, which contains
; a list of Local channels to be dialed, thereby triggering the multiple
; Originate() actions simultaneously instead of linearly
;
   same => n,While($[${EXISTS(${EndPoint})}])

; This statement must be on a single line
   same => n,Set(ToDial=${IF($[${ISNULL(${ToDial})}]?
                     :${ToDial}&)}Local/${EndPoint}@MeetingOriginator)
   same => n,Set(X=$[${X} + 1])
   same => n,Set(EndPoint=${CUT(CalDescription,^,${X})})
   same => n,EndWhile()

; If no values are passed back, then don't bother dialing
   same => n,GotoIf($[${ISNULL(${ToDial})}]?hangup)
   same => n,Dial(${ToDial})

; After our Dial() statement returns, we should be placed into
; the conference room. We are marked, so the conference can start
; (which is indicated by the 'A' flag to MeetMe).
;
   same => n,MeetMe(${CalLocation},dA)
   same => n(hangup),Hangup()

[MeetingOriginator]
exten => _[A-Za-z0-9].,1,NoOp()
   same => n,Set(Peer=${FILTER(A-Za-z0-9,${EXTEN})})

; Originate calls to a peer as passed to us from the Local channel. Upon
; answer, the called party should execute the dialplan located at the
; _meetme-XXXX extension, where XXXX is the conference room number.
;
   same => n,Originate(SIP/${Peer},exten,MeetingOriginator,meetme-${CalLocation},1)
   same => n,Hangup()

; Join the meeting; using the 'w' flag, which means 'wait for marked
; user to join before starting'
;
exten => _meetme-XXXX,1,Verbose(2,Joining a meeting)
   same => n,Answer()
   same => n,MeetMe(${EXTEN:7},dw)
   same => n,Hangup()

Installing both the OpenSSL and PAM development libraries on CentOS can be done with the following command:

$ sudo yum install openssl-devel pam-devel

Installing both the OpenSSL and PAM development libraries on Ubuntu can be done with the following command:

$ sudo apt-get install libssl-dev libpam0g-dev

Now that we have our dependencies satisfied, we can compile the IMAP library that Asterisk will use to connect to our IMAP server.

The first thing to do is change to the thirdparty directory located under the asterisk-complete directory. If you have not already created this directory, do so now:

$ cd ~/src/asterisk-complete
$ mkdir thirdparty
$ cd thirdparty

Next up is downloading the IMAP toolkit and compiling it. The next steps will get the latest version of the IMAP toolkit from the University of Washington’s server (more information about the toolkit is available at http://www.washington.edu/imap/):

$ wget ftp://ftp.cac.washington.edu/mail/imap.tar.Z
$ tar zxvf imap.tar.Z
$ cd imap-2007e

There are a few options we need to pass to the make command when building the IMAP library, and the values you should pass will depend on what platform you’re building on (32-bit vs. 64-bit), if you need OpenSSL support, and whether you need IPv6 support or just IPv4. Table 18.1, “IMAP library compile time options” shows some of the various options you could pass on different platforms.

If you look in the Makefile shipped with the IMAP library, you will find a list of platforms for which the library can be compiled. In our case, we’ll be compiling for either CentOS or Ubuntu with PAM support. If you’re compiling on other systems, take a look in the Makefile for the three-letter code that tells the library how to compile for your platform.

To compile for a 64-bit platform with OpenSSL support and a preference for connecting via IPv4:

$ make lnp EXTRACFLAGS="-fPIC -I/usr/include/openssl" IP6=4

To compile for a 32-bit platform with OpenSSL support and a preference for connecting via IPv4:

$ make lnp EXTRACFLAGS="-I/usr/include/openssl" IP6=4

If you don’t wish to compile with OpenSSL support, simply remove the -I/usr/include/openssl from the EXTRACFLAGS option. If you would prefer connecting by IPv6 by default, simply don’t specify the IP6=4 option.

After compiling the IMAP library, we need to recompile the app_voicemail.so module with IMAP support. The first step is to run the configure script and pass it the --with-imap option to tell it where the IMAP library exists:

$ cd ~/src/asterisk-complete/asterisk/1.8.0
$ ./configure --with-imap=~/src/asterisk-complete/thirdparty/imap-2007e/

Once the configure script has finished executing, we need to enable IMAP voicemail support in menuselect:

$ make menuselect

From the menuselect interface, go to Voicemail Build Options. Within that menu, you should have the option to select IMAP_STORAGE.

After selecting IMAP_STORAGE, save and exit from menuselect and run make install, which will recompile the app_voicemail.so module and install it to the appropriate location. The next step is to configure the voicemail.conf file located in /etc/asterisk/.

Now that we’ve compiled IMAP support into Asterisk, we need to enable it by connecting to an IMAP-enabled server. There are many IMAP servers that you could use, including those supplied with Microsoft servers, Dovecot, and Cyrus on Unix, or a web-based IMAP server such as that supplied by Google’s Gmail.^[159] Our instructions are going to show how to connect Asterisk to a Gmail account with IMAP enabled, as it requires the least amount of effort to get up and running with IMAP voicemail, but these instructions can easily be adapted for use with any existing IMAP server.

Enabling IMAP on your Gmail account

Enabling IMAP support on your Gmail account is straightforward (see Figure 18.1, “Enabling Gmail IMAP”). Once logged into your account, select Settings from the upper-right corner. Then select Forwarding and POP/IMAP support from the task bar under the Settings header. In the IMAP Access section, enable IMAP support by selecting Enable IMAP. After enabling it, click the Save Changes button at the bottom of the screen.

Figure 18.1. Enabling Gmail IMAP

[general]
format=wav49              ; format to store files
imapserver=imap.gmail.com ; IMAP server location
imapport=993              ; port IMAP server listens to
imapflags=ssl             ; flags required for connecting
expungeonhangup=yes       ; delete messages on hangup
pollmailboxes=yes         ; used for message waiting indication
pollfreq=30               ; how often to check for message changes

[shifteight]
100 => 0107,Leif Madsen,leif@shifteight.org
101 => 0523,Jim VanMeggelen,jim@shifteight.org,,attach=no|maxmsg=100
102 => 11042,Tilghman Lesher,,,attach=no|tz=central

[shifteight]
100 => 0107,Leif Madsen,,,|imapuser=leif@shifteight.org|imappassword=secret

*CLI> core set debug 10
*CLI> module reload app_voicemail.so
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info: Trying IP address [74.125.53.109]
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info: Gimap ready for requests 
             from 99.228.XXX.XXX 13if2973206wfc.0
DEBUG[3293]: app_voicemail.c:2757 mm_login: Entering callback mm_login
DEBUG[3293]: app_voicemail.c:2650 mm_exists: Entering EXISTS callback for message 7
DEBUG[3293]: app_voicemail.c:3074 set_update: User leif@shifteight.org mailbox set for 
update.
DEBUG[3293]: app_voicemail.c:2510 init_mailstream: Before mail_open, server: 
             {imap.gmail.com:993/imap/ssl/user=leif@shifteight.org}INBOX, box:0
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info: Reusing connection to 
             gmail-imap.l.google.com/user="leif@shifteight.org"

To install res_jabber, we need the iksemel development library (http://code.google.com/p/iksemel/). If the OpenSSL development library is installed, res_jabber will also utilize that for secure connections (this is recommended). We can install both on CentOS with the following command:

$ sudo yum install iksemel-devel openssl-devel

To install res_jabber, we need the iksemel development library. If the OpenSSL development library is installed, res_jabber will also utilize that for secure connections (this is recommended). We can install both on Ubuntu with the following command:

$ sudo apt-get install libiksemel-dev libssl-dev

Before we can start sending messages to our XMPP buddies, we need to connect to an XMPP-enabled server. We’re going to utilize the XMPP server at Google, as it is open and easily accessible by anyone. To do so, we need to configure the jabber.conf file in our /etc/asterisk/ configuration directory. The following example will connect us to the XMPP server at Google.

Our jabber.conf file should look like this:

[general]
debug=no
autoprune=no
autoregister=yes
auth_policy=accept

[asterisk]
type=client
serverhost=talk.google.com
username=asterisk@shifteight.org
secret=<super_secret_password>
port=5222
usetls=yes
usesasl=yes
status=available
statusmessage="Ohai from Asterisk"

Let’s take a quick look at some of the options we just set so you understand what is going on. The options are described in Table 18.3, “jabber.conf options”. Note that the first four options are set in the [general] section, and the others are set in the peer section.

After configuring our jabber.conf file, we can load (or reload) the res_jabber.so module. We can do this from the console with jabber reload:

*CLI> jabber reload
Jabber Reloaded.

and check the connection with the jabber show connections command:

*CLI> jabber show connections
Jabber Users and their status:
       User: asterisk@shifteight.org    - Connected
----
   Number of users: 1

If you’re having problems getting connected, you can try unloading the module and then loading it back into memory. If you’re still having problems, you can run the jabber purge nodes command to remove any existing or bad connections from memory. Beyond that, check your configuration and verify that you don’t have any configuration problems or typos. Once you’ve gotten connected, you can move on to the next sections, where the fun starts.

The JabberSend() dialplan application is used for sending messages to buddies from the Asterisk dialplan. You can use this application in any place that you would normally utilize the dialplan, which makes it quite flexible. We’re going to use it as a screen pop application for sending a message to a client prior to placing a call to the user’s phone. Depending on the client used, you may be able to have the message pop up on the user’s screen from the task bar.

Here is a simple example to get us started:

[LocalSets]
exten => 104,1,Answer()

; *** This line should not have any line breaks
   same => n,JabberSend(asterisk,jim@shifteight.org,Incoming call from 
${CALLERID(all)})

   same => n,Dial(SIP/0000FFFF0002,30)
   same => n,Hangup()

This example demonstrates how to use the JabberSend() application to send a message to someone prior to dialing a device. Let’s break down the values we’ve used. The first argument, asterisk, is the section header we defined in the jabber.conf file as [asterisk]. In our jabber.conf example, we set up a user called asterisk@shifteight.org to send messages via the Google XMPP server, and asterisk is the section name we defined. The second argument, jim@shifteight.org, is the buddy we’re sending the message to. We can define any buddy here, either as a bare JID (as we’ve done above) or as a full JID with a resource (e.g., jim@shifteight.org/laptop). The third argument to JabberSend() is the message we want to send to the buddy. In this case we’re sending Incoming call from ${CALLERID(all)}, with the CALLERID() dialplan function being used to enter the caller ID information in the message.

Obviously, we would have to further build out our dialplan to make this useful: specifically, we’d have to associate the buddy name (e.g., jim@shifteight.org) with the device we’re calling (SIP/0000FFFF0002) so that we’re sending the message to the correct buddy. You can save these associations in any one of several locations, such as the in AstDB, in a relational database retrieved with func_odbc, or even in a global variable.

The JABBER_RECEIVE() dialplan function allows us to receive responses via XMPP messages, capture those responses, and presumably act on them. We would typically use the JABBER_RECEIVE() function in conjunction with the JabberSend() dialplan application, as we are likely to need to send a message to someone and prompt him with the acceptable values he can return. We could use the JABBER_RECEIVE() function either personally, to direct calls to a particular device such as a cell phone or desk phone, or as a text version of an auto attendant to be used when people who are likely to have difficulty hearing the prompts dial in (e.g., users who are deaf or work at noisy job sites). In the latter case, the system would have to be preconfigured to know where to send the messages to, perhaps based on the caller ID of the person calling.

Here is a simple example that sends a message to someone, waits for a response, and then routes the call based on the response:

exten => 106,1,Answer()

   ; All text must be on a single line.
   same => n,JabberSend(asterisk,leif.madsen@gmail.com,Incoming call from
${CALLERID(all)}. Press 1 to route to desk. Press 2 to send to voicemail.)

   same => n,Set(JabberResponse=${JABBER_RECEIVE(asterisk,leif@shifteight.org)})
   same => n,GotoIf($["${JabberResponse}" = "1"]?dial,1)
   same => n,GotoIf($["${JabberResponse}" = "2"]?voicemail,1)
   same => n,Goto(dial,1)

exten => dial,1,Verbose(2,Calling our desk)
   same => n,Dial(SIP/0000FFFF0002,6)
   same => n,Goto(voicemail,1)

exten => voicemail,1,Verbose(2,VoiceMail)

; *** This line should not have any line breaks
   same => n,Set(VoiceMailStatus=${IF($[${ISNULL(${DIALSTATUS})} 
| "${DIALSTATUS}" = "BUSY"]?b:u)})

   same => n,Playback(silence/1)
   same => n,VoiceMail(100@lmentinc,${VoiceMailStatus})
   same => n,Hangup()

Our simple dialplan first sends a message to a Jabber account (leif@shifteight.org) via our systems’ Jabber account (asterisk), as configured in jabber.conf. We then use the JABBER_RECEIVE() dialplan function to wait for a response from leif@shifteight.org. The default timeout is 5 seconds, but you can specify a different timeout with a third argument to JABBER_RECEIVE(). For example, to wait 10 seconds for a response, we could have used a line like this:

Set(JabberResponse=${JABBER_RECEIVE(asterisk,leif@shifteight.org,10)})

Once we’ve either received a response or the timeout has expired, we move on to the next line of the dialplan, which starts checking the response saved to the ${JabberResponse} channel variable. If the value is 1, we continue our dialplan at dial,1 of the current context. If the response is 2, we continue our dialplan at voicemail,1. If no response (or an unknown response) is received, we continue the dialplan at dial,1.

The dialplan at dial,1 and voicemail,1 should be fairly self-evident. This is a non-production example; some additional dialplan should be implemented to make the values dynamic.

There is a disadvantage to the way we’ve implemented the JABBER_RECEIVE() function, though. Our function blocks, or waits, for a response from the endpoint. If we set the response value low to minimize delay, we don’t give the user we sent the message to much time to respond. However, if we set the response long enough to make it comfortable for the user to send a response, we cause unnecessary delay in calling a device or sending to voicemail.

We can skirt around this issue by using a Local channel. This allows us to execute two sections of dialplan simultaneously, sending a call to the device at the same time we’re waiting for a response from JABBER_RECEIVE(). If we get a response from JABBER_RECEIVE() and we need to do something, we can Answer() the line and cause that section of dialplan to continue. If the device answers the phone, our dialplan with JABBER_RECEIVE() will just be hung up. Let’s take a look at a modified dialplan that implements the Local channel:

exten => 106,1,Verbose(2,Example using the Local channel)
   same => n,Dial(Local/jabber@${CONTEXT}/n&Local/dial@${CONTEXT}/n)

exten => jabber,1,Verbose(2,Send an XMPP message and expect a response)

; *** This line should not have any line breaks
   same => n,JabberSend(asterisk,leif.madsen@gmail.com,Incoming call from 
${CALLERID(all)}. Press 2 to send to voicemail.)

   same => n,Set(JabberResponse=${JABBER_RECEIVE(asterisk,leif@shifteight.org,6)})
   same => n,GotoIf($["${JabberResponse}" = "2"]?voicemail,1)
   same => n,Hangup()

exten => dial,1,Verbose(2,Calling our desk)
   same => n,Dial(SIP/0000FFFF0002,15)
   same => n,Goto(voicemail,1)

exten => voicemail,1,Verbose(2,VoiceMail)
   same => n,Answer()

; *** This line should not have any line breaks
   same => n,Set(VoiceMailStatus=${IF($[${ISNULL(${DIALSTATUS})} 
| "${DIALSTATUS}" = "BUSY"]?b:u)})

   same => n,Playback(silence/1)
   same => n,VoiceMail(100@lmentinc,${VoiceMailStatus})
   same => n,Hangup()

By adding a Dial() statement at the beginning and shifting our Jabber send and receive functionality into a new extension called jabber, we ensure that we can simultaneously call the dial extension and the jabber extension.

Notice that we removed the Answer() application from the first line of the example. The reason for this is because we want to Answer() the line only after a device has answered (which causes the jabber extension to be hung up); otherwise, we want the voicemail extension to Answer() the line. If the voicemail extension has answered the line, that means either the jabber extension has received a response and was told to Goto() the voicemail extension, or the Dial() to our device timed out, causing the voicemail extension to be executed, thereby causing the line to be Answer()ed.

With the examples provided here serving as a springboard, you should be able to develop rich applications that make use of sending and receiving messages via XMPP servers. Some other dialplan applications and functions exist that may help in the development of your application, such as JABBER_STATUS() (or the JabberStatus() dialplan application), which is used for checking on the status of a buddy; the JabberJoin() and JabberLeave() applications, which are used for joining and leaving XMPP conference rooms; and the JabberSendGroup() application, which allows you to send messages to an XMPP chat room.

Once we’re connected via res_jabber, we can configure the gtalk.conf file, which is used for accepting incoming calls from the Google network. The following configuration enables the guest account, which is required to accept incoming calls. There is currently no support for authenticating incoming calls and then separating and sending them to different contexts, which you may be used to from the configuration of other channel drivers in Asterisk. For now chan_gtalk is fairly simple, but future versions of Asterisk may add this feature.

Our gtalk.conf file looks like this:

[general]
bindaddr=0.0.0.0        ; Address to bind to
allowguests=yes         ; Allow calls from people not in contact list

; Optional arguments
; externip=<external IP of server>
; stunaddr=<stun.yourdomain.tld>

[guest]                 ; special account for options on guest account
disallow=all                            
allow=ulaw
context=gtalk_incoming
connection=asterisk     ; connection name defined in jabber.conf

If your Asterisk system lives behind NAT, you may need to add some additional options to the [general] section in order to place the correct IP address into the headers. If you have a static external IP address, you can use the externip option to specify it. Alternatively, you could use the stunaddr option to specify the address of your STUN server, which will then look up your address from an external server and place that information into the headers.

Let’s discuss briefly the options we’ve configured in gtalk.conf. In the [general] section, we have set the bindaddr option to 0.0.0.0, which means to listen on all interfaces.^[160] You can also specify a single interface to listen on by specifying the IP address of that interface. The next line is allowguests, which can be set to either yes or no but is only useful when set to yes. Because the module does not offer the ability to specify different control mechanisms for different users, all users are treated as guests.^[161]

Next we’ve specified the [guest] account, which will let us accept calls from Google Voice and Google Talk users. This account is only used for incoming calls. When placing outgoing calls, we’ll use the account specified in the jabber.conf file. Within the [guest] account, we’ve disabled all codecs with the disallow=all option, and then specifically enabled the ulaw codec with allow=ulaw on the following line. Incoming calls are then directed to the gtalk_incoming context with the context option. We specify which account calls will be coming from with the connection option, which we’ve set to the account created in jabber.conf.

The chan_gtalk module does not support reloading the configuration. If you change the configuration, you will have to either restart Asterisk or unload and reload the module, which can only be done when no GTalk calls are up. You can do that using the following commands:

*CLI> module unload chan_gtalk.so
*CLI> module load chan_gtalk.so

To allow calls from other Google Talk users, we need to configure our dialplan to accept incoming calls. Inside your extensions.conf file, add the [gtalk_incoming] context:

[gtalk_incoming]
exten => s,1,Verbose(2,Incoming Gtalk call from ${CALLERID(all)})
   same => n,Answer()
   same => n,Dial(SIP/0000FFFF0001,30)
   same => n,Hangup()

We’ve now configured a simple test dialplan that will send calls to the SIP/0000FFFF0001 device and wait 30 seconds before hanging up the line. The s extension can be used to match any incoming call from Google Talk or Google Voice, but if you have multiple accounts that could be coming into this context, you can match different users by specifying the username portion of the Gmail email address as the extension. So, for example, if we had a user my_asterisk_user@gmail.com, the username portion would be my_asterisk_user, and this is what we’d specify in [gtalk_incoming]:

[gtalk_incoming]
exten => my_asterisk_user,1,Verbose(2,Gtalk call from ${CALLERID(all)})
   same => n,Answer()
   same => n,Dial(SIP/0000FFFF0001,3)
   same => n,Hangup()

The order of rules used for matching incoming calls to chan_gtalk is:

The configuration for accepting calls from Google Voice is similar (if not identical) to that for Google Talk, which we set up in the preceding section. A little tip, though, is that sometimes you can’t disable the call screening functionality (for some reason we still got it even when we’d disabled it in the Google Voice control panel). If you run into this problem but don’t want to have to screen your calls, you can automatically send the DTMF prior to ringing your device by adding the two boldface lines shown here prior to performing the Dial():

[gtalk_incoming]
exten => s,1,Verbose(2,Incoming call from ${CALLERID(all)})
   same => n,Answer()
   same => n,Wait(2)
   same => n,SendDTMF(2)
   same => n,Dial(SIP/0000FFFF0001,30)
   same => n,Hangup()

Here, we’re using the Wait() and SendDTMF() applications to first wait 2 seconds after answering the call (which is the time when the call screening message will start) and then accept the call automatically (by sending DTMF tones for the number 2). After that, we then send the call off to our device.

To place a call to a Google Talk user, configure your dialplan like so:

[LocalSets]
exten => 123,1,Verbose(2,Extension 123 calling some_user@gmail.com)
   same => n,Dial(Gtalk/asterisk/some_user@gmail.com,30)
   same => n,Hangup()

The Gtalk/asterisk/some_user@gmail.com part of the Dial() line can be broken into three parts. The first part, Gtalk, is the protocol we’re using for placing the outgoing call. The second part, asterisk, is the account name as defined in the jabber.conf file. The last part, some_user@gmail.com, is the location we’re attempting to place a call to.

To place calls using Google Voice to PSTN numbers, create a dialplan like the following:

[LocalSets]
exten => _1NXXNXXXXXX,1,Verbose(2,Placing call to ${EXTEN} via Google Voice)
   same => n,Dial(Gtalk/asterisk/+${EXTEN}@voice.google.com)
   same => n,Hangup()

Let’s discuss the Dial() line briefly, so you understand what is going on. We start with Gtalk, which is the technology we’ll use to place the call. Following that, we have defined the asterisk user as the account we’ll use to authenticate with when placing our outgoing call (this is configured in jabber.conf). Next is the number we’re attempting to place a call to, as defined in the ${EXTEN} channel variable. We’ve prefixed the ${EXTEN} channel variable with a plus sign (+), as it’s required by the Google network when placing calls. We’ve also appended @voice.google.com to let the Google servers know this is a call that should be placed through Google Voice^[162] as opposed to to another Google Talk user.

While the README file that comes with the Skype module helps to document the chan_skype.conf configuration, and the sample chan_skype.conf file is well-documented, it is worth showing a simple version of the configuration for the purposes of documenting the usage of Skype from the dialplan.

Our example Skype user will be pbx.shifteight.org. We’ll configure this user in chan_skype.conf. There are additional options that could be set here, but for our purposes we’re keeping it simple:

[general]
default_user=pbx.shifteight.org

[pbx.shifteight.org]
secret=my_secret_pass
context=skype_incoming
exten=start
buddy_autoadd=true

The default_user option in the [general] section is used to control which account we should use when placing calls via Skype. If we had multiple accounts, the default_user would be used when placing calls unless we specified a different user to place the call as (we’ll discuss this further in the next section).

We’ve also defined the password (secret), the context incoming calls will enter into, and the extension (exten) that will be executed within the context. If we had multiple Skype users and wanted to control all of them from the same context, we could give them each different extension values, such as exten=leifmadsen or exten=russellbryant.

Additionally, we’ve enabled the ability to automatically add people who contact us to our buddies list.

Placing a call to a Skype buddy is relatively straightforward. Like with other channel types in Asterisk, the Skype channel type is used to place calls to endpoints on the Skype network.

Utilizing the Dial() application from the dialplan, we can place calls to other Skype users:

[LocalSets]
exten => 100,1,Answer()
   same => n,Dial(Skype/vuc.me,30)
   same => n,Playback(silence/1&user&is-curntly-unavail)
   same => n,Hangup()

Our dialplan simply answers the call and attempts to place a call to vuc.me,^[164] wait 30 seconds for that user to answer, and, if there is no answer, play back a message saying that the user is currently unavailable before hanging up. We could, of course, be more elaborate with our dialplan; for example, we could turn this into a Macro() or GoSub() routine so we just needed to pass in the name of the person we wish to call.

Unfortunately, if you’re utilizing a device that only has a number pad for dialing, you’ll need to assign extension numbers to all your favorite Skype buddies. However, we’ve come up with a clever way of reading back your online buddies to you, which we’ll describe in the section called “Calling your Skype buddies without assigning extension numbers”.

If you have a softphone, though, you should have the ability to place calls by dialing names directly. We can use this to our advantage by creating a pattern match in our dialplan with the prefix of SKYPE:

[LocalSets]
exten => _SKYPE-.,1,Verbose(2,Dialing via Skype)
   same => n,Set(NameToDial=${FILTER(a-zA-Z0-9.,${EXTEN:6})})
   same => n,Playback(silence/1&pls-wait-connect-call)
   same => n,Dial(Skype/${NameToDial},30)
   same => n,Playback(user&is-curntly-unavail)
   same => n,Hangup()

By dialing SKYPE-vuc.me, we can dial the VoIP Users Conference via Skype from our softphone. The FILTER() function is used here to control what we’re allowed to pass to the Dial() application. If we didn’t do any filtering, someone could potentially send a string like SKYPE-nobody&SIP/my_itsp/4165551212, replacing the number 4165551212 with a number that is very expensive to call. By using FILTER(), we restrict the allowable characters to alphanumeric characters and periods.

After that, we’re simply passing the string to the Dial() application and waiting for an answer for 30 seconds. If no one answers, an audio message is played back to the caller stating that the user is unavailable and then the call is hung up.

To receive calls, you simply need to configure your user in the chan_skype.conf file as described in the section called “Configuring chan_skype.conf”. Once you’ve done that, you can configure your dialplan to answer calls like so:

[skype_incoming]
exten => start,1,Verbose(2,Incoming Skype Call)
   same => n,Answer()
   same => n,Dial(SIP/0000FFFF0001,30)
   same => n,Playback(user&is-curntly-unavail)
   same => n,Hangup()

Obviously, you can change this section of the dialplan to be more elaborate; all we’ve done is configured the dialplan to call our SIP device at 0000FFFF0001, wait for an answer for 30 seconds, and then (if there is no answer or the device is busy or unavailable) play back a prompt that says the user is currently unavailable, followed by a hangup.

We’ve just shown you how to place and receive calls via Skype. The following sections will show you how to send and receive messages via the Skype network, and how to place calls to your Skype buddies without assigning extension numbers to them.

Sending and receiving messages via Skype is similar to doing this via XMPP (Jabber), which we described in the section called “Sending messages with JabberSend()” and the section called “Receiving messages with JABBER_RECEIVE()”, so we won’t go into quite the detail in these sections as we did there. Please review the sections about XMPP messaging before continuing, as we’ll be using the same basic dialplans to accomplish sending and receiving of messages via Skype, while making adjustments to use the appropriate dialplan applications and functions.

The primary thing to remember is that messages are sent with the dialplan application SkypeChatSend() and received with the dialplan function SKYPE_CHAT_RECEIVE(). Additionally, messages can only be received when the SKYPE_CHAT_RECEIVE() function has been called from the dialplan, and it blocks (does not continue in the dialplan) while waiting for a message.

Sending a message from the dialplan to a Skype buddy is relatively straightforward. Here is a simple dialplan we can use to send a message from Asterisk to someone on the Skype network:

[LocalSets]
exten => 104,1,Answer()

; *** This line should not have any line breaks
   same => n,SkypeChatSend(pbx.shifteight.org,tfot.madsen,Incoming call from 
${CALLERID(all)})

   same => n,Dial(SIP/0000FFFF0002,30)
   same => n,Hangup()

Our dialplan is simple. We created a test extension of 104 that answers the line, then sends a message to Skype user tfot.madsen from the pbx.shifteight.org account (which we configured in the chan_skype.conf file). The message sent is “Incoming call from ${CALLERID(all)}”, where the caller ID is provided by the CALLERID() function. After sending our message, we then dial the device located at 0000FFFF0002 and hang up if no one answers within 30 seconds.

That’s it for sending messages via Skype. Now let’s look at some of the ways we can receive messages from Skype. Here is the simple example we explored in the section called “Receiving messages with JABBER_RECEIVE()”), with a few changes made to reflect the technology. This time, we’ll be replacing JabberSend() and JABBER_RECEIVE() with the SkypeChatSend() and SKYPE_CHAT_RECEIVE() dialplan application and function, respectively:

exten => 106,1,Answer()

   ; All text must be on a single line.
   same => n,SkypeChatSend(pbx.shifteight.org,tfot.madsen,Incoming call from
${CALLERID(all)}. Press 1 to route to desk. Press 2 to send to voicemail.)

   ; Wait for a response for 6 seconds.
   ; *** This line should not have any line breaks
   same => n,Set(SkypeResponse=
${SKYPE_CHAT_RECEIVE(pbx.shifteight.org,tfot.madsen,6)})

   same => n,GotoIf($["${SkypeResponse}" = "1"]?dial,1)
   same => n,GotoIf($["${SkypeResponse}" = "2"]?voicemail,1)
   same => n,Goto(dial,1)

exten => dial,1,Verbose(2,Calling our desk)
   same => n,Dial(SIP/0000FFFF0002,6)
   same => n,Goto(voicemail,1)

exten => voicemail,1,Verbose(2,VoiceMail)

; *** This line should not have any line breaks
   same => n,Set(VoiceMailStatus=${IF($[${ISNULL(${DIALSTATUS})} 
| "${DIALSTATUS}" = "BUSY"]?b:u)})

   same => n,Playback(silence/1)
   same => n,VoiceMail(100@lmentinc,${VoiceMailStatus})
   same => n,Hangup()

There you have it—sending and receiving messages via the Skype network!

We’ve essentially implemented a screen pop solution for incoming calls, but by allowing messages to be sent back to Asterisk via Skype within a defined period of time, we’ve also created a solution for redirecting calls prior to ringing any devices. A more functional version of the dynamic routing dialplan we just explored was developed in the section about JABBER_RECEIVE() earlier in this chapter: it used the Local channel to get around the dialplan blocking issue, enabling calls can be routed even after a device has started to be rung.

While working on this book, we had some issues with trying to come up with clever ways to use a text-to-speech engine. It seemed that dynamic data would need to be involved for text-to-speech to really make a lot of sense—otherwise, why not use prerecorded prompts instead? However, an idea finally came to us, based on the fact that having to assign extension numbers to each Skype user we wanted to call was not only cumbersome, but was a mental exercise we weren’t willing to take on.

The following dialplan makes use of the SKYPE_BUDDIES() and SKYPE_BUDDY_FETCH() dialplan functions to retrieve all the Skype buddies in memory on the server, and to read those buddies’ names back to you along with their statuses. After each buddy name is read, a prompt asking if this is who you wish to call is presented, with the option of asking for another buddy from the list. We’ve utilized the Festival() application for this example (the configuration and setup of which can be found in the section called “Festival”) to read back the users’ names. Once a buddy has been marked as selected, it is then dialed using the Dial() application.

Our implementation is as follows:

[LocalSets]
exten => 75973,1,Verbose(2,Read off list of Skype accounts)
   same => n,Answer()
   same => n,Set(ID=${SKYPE_BUDDIES(pbx.shifteight.org)})
   same => n(new_buddy),Set(ARRAY(buddy,status)=${SKYPE_BUDDY_FETCH(${ID})})
   same => n,GotoIf($[${ISNULL(${buddy})}]?no_more_buddies)
   same => n,Festival(${buddy} is ${status})
   same => n,Read(Answer,if-correct-press&digits/1&otherwise-press&digits/2,1)
   same => n,GotoIf($[${Answer} = 2]?new_buddy)
   same => n,Dial(Skype/${buddy},30)
   same => n,Playback(user&is-curntly-unavail)
   same => n,Hangup()

exten => no_more_buddies,1,Verbose(2,No more buddies to find)
   same => n,Playback(dir-nomore)
   same => n,Hangup()

On Ubuntu, we need to install the openldap-dev package to provide the dependency for the res_config_ldap module:

$ sudo apt-get install openldap-dev

On CentOS, we need to install the openldap-devel package to provide the dependency for the res_config_ldap module:

$ sudo yum install openldap-devel

The res_ldap.conf.sample file is a good place to start because it contains a good set of templates. At the top of the file, though, under the [_general] section, we need to configure how Asterisk is going to connect to our LDAP server. Our first option is url, which will determine how to connect to the server. We have defined a connection as ldap://172.16.0.103:389, which will connect to the LDAP server at IP address 172.16.0.103 on port 389. If you have a secure connection to your LDAP server, you can replace ldap:// with ldaps://. Additionally, we have set protocol=3 to state that we’re connecting with protocol version 3, which in most (if not all) cases will be correct.

The last three options, basedn, user, and pass, are used for authenticating to our LDAP server. We need to specify:

If we put it all together, we end up with something like the following:

[_general]
url=ldap://172.16.0.103:389
protocol=3
basedn=dc=shifteight,dc=org
user=cn=admin,dc=shifteight,dc=org
pass=canada

Beyond this, in the rest of the sample configuration file we’ll see lots of templates we can use for mapping the information in Asterisk onto our LDAP schema. Lets take a look at the first lines of the [sip] template that we’ll be using to map the information of our SIP peers into the LDAP database:

[sip]
name = cn
amaflags = AstAccountAMAFlags
callgroup = AstAccountCallGroup
callerid = AstAccountCallerID
...
lastms = AstAccountLastQualifyMilliseconds
useragent = AstAccountUserAgent
additionalFilter=(objectClass=AsteriskSIPUser)

On the left side we have the field name Asterisk will be looking up, and on the right is the mapping to the LDAP schema for the request. Our first set of fields is mapping the name field to the cn field on the LDAP server. If you look back at the data we imported in the section called “Configuring OpenLDAP”, you’ll see that we have created a user and assigned the value of RussellBryant to the cn field. So, in this case, we’re mapping the authentication name (the name field) from the SIP user to the value of the cn field in the LDAP server (RussellBryant).

This goes for the rest of the values all the way down, with some fields (i.e., useragent, lastms, ipaddr, etc.) simply needing to exist so Asterisk can write information (e.g., registration information) to the LDAP server.

Our next step is to tell Asterisk what information to load via realtime and what technology to use. Using the extconfig.conf file, we have the option of loading several modules dynamically (and we can also load files statically). For more information about Asterisk realtime, see the section called “Using Realtime”.

For our example, we’re going to configure the sipusers and sippeers dynamic realtime objects to load our SIP peers from LDAP. In the following example, we have a line like this:

          ldap,"ou=people,dc=shifteight,dc=org",sip
        

We’ve specified three arguments. The first is ldap, which is the technology we’re going to use to connect to our realtime object. There are other technologies available, such as odbc, pgsql, curl, and so on. Our second argument, enclosed in double quotes, specifies which database we’re connecting to. In the case of LDAP, we’re connecting to the object-unit people within the domain shifteight.org. Lastly, our third argument, sip, defines which template we’re using (as defined in res_ldap.conf) to map the realtime data to the LDAP database.

To define the use of sipusers and sippeers from the LDAP server, we would enable these lines in extconfig.conf:

sipusers => ldap,"ou=people,dc=shifteight,dc=org",sip
sippeers => ldap,"ou=people,dc=shifteight,dc=org",sip

These steps are optional for configuring SIP for realtime, although you will likely expect things to work in the manner we’re going to describe. In the sip.conf file, we will enable a few realtime options that will cache information into memory as it is loaded from the database. By doing this, we’ll allow Asterisk to place calls to devices by simply looking at the information stored in memory. Not only does caching make realtime potentially more efficient, but things like device state updates simply can’t work unless the devices are cached in memory.

To enable peer caching in Asterisk, use the rtcachefriends option in sip.conf:

rtcachefriends=yes

There are additional realtime options as well, such as rtsavesysname, rtupdate, rtautoclear, and ignoreregexpire. These are all explained in the sip.conf.sample file located within your Asterisk source.

Installing Festival and its dependencies on CentOS is straightforward. Simply use yum to install the festival package:

$ sudo yum install festival

To install Festival and its dependencies on Ubuntu, simply use apt-get to install the festival package:

$ sudo apt-get install festival

With Festival installed, we need to modify the festival.scm file in order to enable Asterisk to connect to the Festival server. On both CentOS and Ubuntu, the file is located in /usr/share/festival/. Open the file and place the following text just above the last line, (provide 'festival):

(define (tts_textasterisk string mode)
"(tts_textasterisk STRING MODE)
Apply tts to STRING. This function is specifically designed for
use in server mode so a single function call may synthesize the string.
This function name may be added to the server safe functions."
(let ((wholeutt (utt.synth (eval (list 'Utterance 'Text string)))))
(utt.wave.resample wholeutt 8000)
(utt.wave.rescale wholeutt 5)
(utt.send.wave.client wholeutt)))

After adding that, you need to start the Festival server:

$ sudo festival_server 2>&1 > /dev/null &

Using menuselect from your Asterisk source directory, verify that the app_festival application has been selected under the Applications heading. If it was not already selected, be sure to run make install after selecting it to install the Festival() dialplan application.

Before you can use the Festival() application, you need to tell Asterisk how to connect to the Festival server. The festival.conf file is used for controlling how Asterisk connects to and interacts with the Festival server. The sample festival.conf file located in the Asterisk source directory is a good place to start, so copy festival.conf.sample from the configs/ subdirectory of your Asterisk source to the /etc/asterisk/ configuration directory now:

$ cp ~/asterisk-complete/asterisk/1.8/configs/festival.conf.sample \
/etc/asterisk/festival.conf

The default configuration is typically enough to connect to the Festival server running on the local machine, but you can optionally configure parameters such as the host where the Festival server is running (if remote), the port to connect to, whether to enable caching of files (defaults to no), the location of the cache directory (defaults to /tmp), and the command Asterisk passes to the Festival server.

You can verify that the Festival() dialplan application is accessible by running core show application festival from the Asterisk console:

*CLI> core show application festival

If you don’t get output, you may need to load the app_festival.so module:

*CLI> module load app_festival.so

Verify that the app_festival.so module exists in /usr/lib/asterisk/modules/ if you’re still having issues with loading the module.

After loading the Festival() application into Asterisk, you need to create a test dialplan extension to verify that Festival() is working:

[LocalSets]
exten => 203,1,Verbose(2,This is a Festival test)
   same => n,Answer()
   same => n,Playback(silence/1)
   same => n,Festival(Hello World)
   same => n,Hangup()

Reload the dialplan with the dialplan reload command from the Asterisk console, and test out the connection to Festival by dialing extension 203.

Alternatively, if you’re having issues with the Festival server, you could use the following method to generate files with the text2wave application supplied with the festival package:

exten => 202,1,Verbose(2,Trying out Festival)
   same => n,Answer()

; *** This line should not have any line breaks
   same => n,System(echo "This is a test of Festival" 
| /usr/bin/text2wave -scale 1.5 -F 8000 -o /tmp/festival.wav)

   same => n,Playback(/tmp/festival)
   same => n,System(rm -f /tmp/festival.wav)
   same => n,Hangup()

You should now have enough to get started with generating text-to-speech audio for your Asterisk system. The audio quality is not brilliant, and the speech generated is not clear enough to be easy to understand over a telephone, but for development and testing purposes Festival is an application that can fill the gap until you’re ready for a more professional-sounding text-to-speech generator such as Cepstral.