Dialplan

A "dialplan" in the Adhearsion world of telecom terminology means "the call flow logic which controls phone calls". Virtually all Adhearsion applications have a file named dialplan.rb in the app's root directory and is invoked in response to an AGI call from Asterisk. This page is an overview of the dialplan.rb and how to use it effectively in your application.

Before the dialplan can be executed, you must ensure Asterisk has been installed and configured properly. See the Asterisk Installation page for help.

The Dialplan at a glance

To jump right in, let's analyze the following Adhearsion dialplan:

internal {
  play 'hello-world'
}

incoming {
  play 'goodbye'
}

outgoing {
  dial("IAX2/my.id@voipjet/19095551234", :name=>"John Doe", :caller_id=>"9095551234")
}

Notes on terminology

There exists little unanimous support for anything in the telephony world and Adhearsion's use of some terms has been criticized by orthodox telephony engineers. The official position of the Adhearsion project is that telephony terminology in general sucks and Adhearsion has no reservations about repurposing words, even if it breaks a tradition that's been in place for half a century.

The term "dial plan" in traditional telephony circles usually means a set of (usually static) digit patterns which a particular phone considers to be valid. In traditional telephony jargon, Adhearsion's dialplan would be IVR code, but it's strongly recommended to never use the term IVR in the context of Adhearsion simply because it's a legacy jargon that Adhearsion tries to distance itself from for simplicity's sake.

Also note that the term "dialplan" shouldn't be spelled "dial plan" and shouldn't be capitalized. It's one word because Adhearsion assigns it a special meaning.

Methods

Adhearsion::VoIP::Asterisk Module

• check_voicemail
• dial
• duration_of
• say_digits
• voicemail_main

Adhearsion::VoIP::Asterisk:Commands Module

• answer
• disable_feature
• dtmf
• enable_feature
• execute
• get_variable
• hangup
• input
• join
• jump_to
• last_dial_status
• last_dial_successful?
• last_dial_unsuccessful?
• menu
• messages_waiting?
• next_message
• play
• queue
• raw_response
• read
• record
• set_variable
• speak
• variable
• voicemail
• with_next_message
• write

Specifying more than one dialplan file

You may want to segment your lengthy dialplan into more than one file. To do this, you may edit the '.ahnrc' file that is in the root directory of your Adhearsion project. By default, the following configuration is in the '.ahnrc' file:

dialplan: dialplan.rb

dialplan: ["dialplan.rb", "dialplan2.rb", "my_project/dialplan3.rb"]

Contexts

Adhearsion contexts are ways of defining entry points for calls to begin in the dialplan.rb file.

Asterisk contexts with underscores.

When a call comes into Adhearsion from extensions.conf, Adhearsion will automatically execute its own context which carries the same name as from extensions.conf. This creates a small incompatibility in Asterisk's acceptance of dashes as a context name. Adhearsion works around this by automatically converting any dashes to underscores. For example, the extensions.conf context name "my-context" would execute the Adhearsion context "my_context".

How Adhearsion parses dialplan.rb

Adhearsion will only parse dialplan.rb when (1) Adhearsion initializes or (2) when dialplan.rb is modified. For this reason, the parsing of dialplan.rb occurs outside of the context of any call and the context bodies (the code between the curly braces) are simply stored off as objects. When a call comes in, Adhearsion uses a feature called instance_eval to run your contexts within an ExecutionEnvironment object specific to that particular call.

Defining contexts programmatically

Because the dialplan.rb is pure Ruby, you have the full language at your disposal when defining contexts. Usually you don't need this robustness but it does allow you to do things like this:

1.upto 5 do |number|
  send "context_#{number}" do
    play "Hello world"
  end
end

Additionally, because the contexts are interpreted outside of any ExecutionEnvironment object, you can't do something like this:

name = get_variable "CONTEXT_SUFFIX"
send "context_#{name}" do
  play "hello-world"
end

Accessing the Asterisk Manager Interface (AMI) from your Dialplan

If you have connected your Adhearsion instance to the AMI, then it is possible to use this interface from the Dialplan. This could either be in your dialplan.rb or within a component in 'methods_for :dialplan do'.

options = { "Channel"  => 'SIP/12125551212@sipphone.com',
            "Context"  => 'my_context',
            "Exten"    => 's',    
            "Priority" => '1',              
            "Async"    => 'true' }   

result = Adhearsion::VoIP::Asterisk.manager_interface.originate options

#or you may do a call_int_context as well

result = Adhearsion::VoIP::Asterisk.manager_interface.call_into_context 'SIP/3000', 'my_context'