$ sudo gem install adhearsion
Successfully installed adhearsion-0.8.4
1 gem installed

after adhearsion was installed, you should install some softphone for testing. I recommend using blink on Mac OS.

Now let’s create a first project to play around.

$ ahn create test
      create  
      create  components/simon_game
      create  components/disabled/stomp_gateway
      create  components/disabled/sandbox
      create  components/ami_remote
      create  components/disabled/restful_rpc/spec
      create  config
      create  .ahnrc
      create  components/simon_game/simon_game.rb
      create  components/ami_remote/ami_remote.rb
      create  components/disabled/stomp_gateway/stomp_gateway.rb
      create  components/disabled/stomp_gateway/stomp_gateway.yml
      create  components/disabled/stomp_gateway/README.markdown
      create  components/disabled/restful_rpc/restful_rpc.rb
      create  components/disabled/restful_rpc/restful_rpc.yml
      create  components/disabled/restful_rpc/README.markdown
      create  components/disabled/restful_rpc/example-client.rb
      create  components/disabled/restful_rpc/spec/restful_rpc_spec.rb
      create  components/disabled/sandbox/sandbox.yml
      create  components/disabled/sandbox/sandbox.rb
      create  config/startup.rb
      create  dialplan.rb
      create  events.rb
      create  README
      create  Rakefile

Now we need to set up asterisk extensions.conf for our first adhearsion project. So let’s open /Library/Asterisk/conf/extensions.conf and search for the [default] section and add exten => _X.,1,AGI(agi://127.0.0.1) right at the beginning.
It should now look like this:

[default]
;
; By default we include the demo.  In a production system, you
; probably don't want to have the demo there.
;
exten => _X.,1,AGI(agi://127.0.0.1)

Why the default? For the purpose of testing, this is the fastest way. You can of course use something different, but keep in mind that this MUST match what you will have in your adhearsion dialplan.rb ! But more on that later.

Now open dialplan.rb from your freshly created adhearsion project in your favorite editor.
Remove the lines from the example

adhearsion {
  simon_game
}

And replace them with our first example:

default {
  ahn_log " Extenstion #{extension} was dialed"
}

Note that the default here must match the section of your extensions.conf, so if you used [my_cool_ivr] then your dialplan.rb must look like this:

my_cool_ivr {
  ahn_log " Extenstion #{extension} was dialed"
}

So now start asterisk

$ asterisk -cvvvvv

Start your ahn project

$ ahn start test
 INFO ahn: Adhearsion initialized!
[Sat Jul 24 20:33:55 2010] Adhearsion::VoIP::Asterisk::AGI::Server::RubyServer 0.0.0.0:4573 start

And start Blink and dial 100@127.0.0.1, nothing exciting will happen, but if you check your session where you started adhearsion you will see

[Sat Jul 24 20:34:45 2010] Adhearsion::VoIP::Asterisk::AGI::Server::RubyServer 0.0.0.0:4573 client:64178 localhost<127.0.0.1> connect
 INFO ahn:  Extenstion 100 was dialed

So with very little effort you now have connected Asterisk to ruby, pretty cool. Well, let’s do something more exciting now.
Open up dialplan.rb and add some code in it.

default {
  ahn_log "Extenstion #{extension} was dialed"
  case extension
    when 100
      play "agent-pass"
      login=input 4, :timeout => 1.minute
      ahn_log "got login #{login}"
      if login=="1234"
        play "agent-loginok"
      else
        play "agent-incorrect"
      end
    else
      play "ss-noservice"
  end
}

So if you dial 100@127.0.0.1 you will be asked to enter a pin, with the line login=input 4, :timeout => 1.minute you are telling asterisk that you want 4 digits, and there should be a timeout if nothing happens in one minute.

I did intend to show off some conference features … but it turns out the binary build of asterisk for mac os is missing app_meetme so until I figure that one out I’ll just leave this as it is.

The best way to find out if this works would be to call and see if the call is accepted and if you get something back from your AGI server and you can do this with automatically with Adhearsion!

What you will need is a wav file containing a DTMF sequence. You can create one with Adobe Audition for example (aka Cooledit before Adobe took over). The Trial version is enough to create the DTMF. Use a 300ms pause at least the other settings didn’t really work for me. Also don’t forget to set your Asterisk server to dtmfmod=inband.

I created a new adhearsion project and used the Simon game as start of and modified it to look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

methods_for :dialplan do
  def check_call
    CheckCall.new(self).start
  end
end
 
class CheckCall
 
  def initialize(call)
    @call = call
    @number='12345'
  end
 
  def start
    collect_attempt
    verify_attempt
  end
 
  def collect_attempt
    @attempt = @call.input @number.length,
      :timeout => 10.seconds    
  end
 
  def verify_attempt
    if attempt_correct? 
		# do something here
    else
		# do something else
    end
  end
 
  def attempt_correct?
    @attempt == @number
  end
 
end

What this does is check if the called server sent the DTMF sequence 12345 and if not it would do something.

You cold for example use growl and/or prowl for notification or use some SMS service for notification like lcx.at (I know, shameless self promotion).

Also don’t forget to activate drb in your adhersion project, do this in startup.rb

config.enable_asterisk
config.asterisk.enable_ami :host => "localhost", :username => "amiuser", :password => "amipassowrd", :events => true
 
config.enable_drb :host => "0.0.0.0", :deny => "0.0.0.0", :allow => ["127.0.0.1", "213.123.118.123"]

Ok now all we need is the script that triggers the call. This could look like this:

require 'drb'
@adhearsion = DRbObject.new_with_uri "druby://localhost:9050"
result = @adhearsion.originate({ :channel   => "SIP/....", 
                                 :context   => "checkcall", 
                                 :exten 	=> '4000',
                                 :priority  => 1,
                                 :callerid  => "43123456789",
                                 :async => 'true',                                     
                                 :variable  => "call_launcher=true|sleep_time=3600" })

So, this is it. I know this isn’t really a copy & paste howto, some things are missing but I don’t want to repeat things that can be read in the adhearsion documentation.
Oh, what I forgot to mention, I use a separate server which runs Asterisk to do the checks, the checks are NOT done form the same server I am checking, but I think this should be obvious.
If you need a VPS with this Setup, or need someone to verify your VoIP Servers, feel free to contact me!

So, if you are in the same situation as I was and don’t have time to set up your own asterisk server and find some cheap VoIP routes to your destination, just contact me and I will help you