Dialplan

Ben Langfeld edited this page Apr 11, 2012 · 5 revisions

DEPRECATION NOTICE: This is old documentation relevant to Adhearsion 1.x and will soon be removed. See the main documentation for up-to-date info.

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 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, 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##

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 IVR is a rarely used term in the context of Adhearsion.

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

Adhearsion::VoIP::Asterisk:Commands Module

##Specifying more than one dialplan file##

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

dialplan: dialplan.rb

You may add additional dialplan files by simply passing the dialplan: option an array as follows:

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

If that Ruby seems a bit too complicated, you can also define contexts manually.

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

Normal dialplan methods such as get_variable are not usable outside of any context.

##Accessing the Asterisk Manager Interface (AMI) from your dialplan##

If you 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'
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.