Asterisk Based Implementation

and development platform

Need to communicate?? Asterisk is your answer.
Prepared by: Aziz Zoaib
Asterisk CONSULTANT

Agenda
Asterisk
o
o
o

What is Asterisk?
What Does Asterisk Do?
Asterisk Benefits

Asterisk Architecture
Asterisk as an Application based Platform
o
o
o
o

Block Diagram and Execution Flow

Communication b/w AGI and ExternalAPI
Protocol & Message format
Asterisk Call Processing

Asterisk Gateway Interface

o
o
o

How to execute an AGI program from the Asterisk dial plan?

Communicating with the Asterisk AGI interface
Passing arguments to your AGI program

Asterisk Manager Interface

o
o
o

AMI protocol behavior

AMI Information available for each of these event/action types
AMI Communication

What is Asterisk?

World's most popular open source communications project

Simply to create and deploy a wide range of telephony

applications and services, including
o
o
o
o
o

IP PBXs
VoIP gateways
Call center ACDs
IVR systems
Mobile based applications

Released as open source under the GNU General Public

License (GPL)

What Does Asterisk Do?

Development platform where you can create communications

applications.
Includes all the building blocks needed to create
o PBX system
o IVR system
o Communications solution
The "blocks" in the kit include:
o Drivers for various VoIP protocols and for PSTN interface cards.
o Routing and call handling (incoming and Outbound calls).
o Media management functions (record, play, generate tone, etc.).
o Call detail recording for accounting and billing.
o Transcoding (conversion from one media format to another).
o Protocol conversion (conversion from one protocol to another).
o Database integration.
o Web services integration.

What Does Asterisk Do? (Cont)

o LDAP integration for accessing corporate directory systems.
o Single and multi-party call bridging.
o Call recording and monitoring.
o Integrated "Dialplan" scripting language for call processing.
o External API in any programming language via Asterisk Gateway

Interface (AGI).
o Event notification via Asterisk Manager Interface (AMI).
o Speech synthesis "text-to-speech" in various languages.
o Speech recognition in various languages using third party recognition
engines.

Open nature of Asterisk means that there is no fixed

limit on what it can be made to do.
Asterisk integrators have built everything from very
small IP PBX systems to massive carrier media servers.

Asterisk Benefits
Source code availability, your guarantee for business
continuity
Use of generic hardware means no proprietary lockin
Freely and easily extensible
Reduce cost, improve productivity and improve
customer service
Easy to integrate into External API modules
Extremely cost effective

Asterisk Architecture

Asterisk Architecture
DAHDI

CLI

Applicati
on

Digital
card
drivers

SIP

IAX2

Asterisk
Core

Dialpla
n

Audio/Vid
eo
Codecs

Sys
Config
Drivers

H323

Manager
Interfac
e
Resourc
es

AGI

Asterisk Architecture (Cont)

Asterisk Core:
Heart of any Asterisk system.
Essential components:
o Directly intact with signaling protocols
o Takes care of bridging calls
o Takes care reading the configuration files and loading the other
modules
o Modules are typically files with a .so file extension
o On starts up, it loads these files and adds their functionality to the
system

Dialplan:
Core also contains the dialplan, logic of any Asterisk

system
Dialplan contains a list of instructions that Asterisk should
follow to know how to handle incoming and outgoing calls
on the system

Asterisk Dialplan
Heart of any Asterisk system.
List of rules, instructions and steps guiding the flow of inbound and

outbound calls in Asterisk

Dialplan consists of a exten followed by a Dialplan application.
Devices that dial in match a pattern and follow series of dial plan
applications.
Configure in extensions.conf file
Divided into [Contexts]
Extensions, Priorities, Applications()
exten => 123, 1, Answer()
exten => 123, n, Background(menu_prompt)
exten => 123, n, WaitExten()
...

The dialplan is a procedural language

It is complete with subroutines (macros), Goto commands, conditional

branching
It even provides support for advanced AGI

Asterisk Architecture (Cont)

Asterisk Gateway Interface:
Use to implement external logics utilizing Asterisk.
o Perform advanced logic
o Communicate with databases
o Perform complex tasks that would be hard to do with Dialplan

AGI is an application level API

application developed using AGI
are not bound by the Asterisk
License and are not required to be
re-distributed with the source
Allows an external, user-written
program on any programming
language.
launched from the dial plan via
pipes to control telephony
operations on its associated control
and voice channels.

Dialpla
n

Externa
l
Resour
ce

Sound
File
Asteris
k Core

AGI
Externa
l
Resour
ce

Channe
ls

Externa
l
Resour
ce

Asterisk Architecture (Cont)

AGI Features:
o Provides a standard interface by which external programs may
o
o
o
o

o
o

control the Asterisk dialplan.

Supports languages like Java, C#, PHP etcCan be located on different or on same sever running Asterisk.
Full command over core functionalities of Asterisk.
Uses a TCP socket for communication to the external host which
provides the function of an AGI service, in a manner of the client
server model.
Using Management API user can even manage Asterisk core from
AGI.
User can play prompts from AGI, record files etc etc...

Asterisk as an Application based Platform

Block Diagram of Asterisk based Application platform:

4

Services Request

Services Response

User

Response from ExternalAPI

Asterisk
Asterisk
Core
Core
Dialplan
Dialplan

DB
DB

ExternalAPI
Programmed API

AGI
AGI Script
Script

3
HOST
HOST

Query to ExternalAPI

Asterisk AGI Execution Flow

Diagram
Asterisk
Asterisk

Dialplan
Dialplan

AGI
AGI
Script
Script

External
External
API
API

Step 1 (Call
triggered)

Step 2 (Dialplan
Executed)

Step 3 (AGI
Executed)

Step 6

Step 4 (Query to
ExternalAPI)
Step 5 (Query
Response)

Step 7
Step 8 (AGI
Step 9 (Released)

Termination)

Step 10 (Released)

Steps that occur when an AGI script is executed from within the
Asterisk dialplan

Asterisk AGI Execution Flow

Step#1,2
User trigger the call, asterisk core detects the incoming call and initiate
dialplan.
Step#3
AGI script is being executed from the Asterisk dialplan.
Asterisk will pass a preset number of AGI variables, along with general AGI
execution information to our AGI script, which requires initial processing.
Step#4,5
Once an AGI script has been invoked, all the queries will be sended and
received from AGI to ExternalAPI.
Step#6,7
A preset information flow is performed between the AGI script and Asterisk.
Step#8,9,10
Once an AGI script has terminated its execution, it will return the control back
to Asterisk for the continued execution of the Asterisk dialplan.

ExternalAPI
ExternalAPI is a programmable application is used to allow external systems

to communicate directly with Asterisk AGI.

ExternalAPI can do variety of stuff from consuming web service to

sending/receiving TCP/IP data to operator's modules or fetching a data from

database etc..'.

External API
External
API

DB & Provisioning
Server

Web Server

3rd party system

Communication b/w AGI and ExternalAPI:

Asterisk
Asterisk
AGI
AGI

ExternalAPI
ExternalAPI
Request
<methodcall>
Response
<Response>

Request being
process
Process
completed

Asterisk AGI and ExternalAPI are communicate over TCP/IP socket

connections.

Protocol & Message format

Message exchanged between Asterisk AGI and ExternalAPI

is over TCP socket.
Function call and response messages from Asterisk AGI to
ExternalAPI must be packed in XML format.
Sample request message:
Parameter

Name
<methodCall>
result
<function>provisionService</function>
<Msisdn>0133309331</Msisdn>
resultCode
<cosProfileId>3 </cosProfileId>
<provChannel>IVR</provChannel>
</methodCall>
Sample response message:

<Response>
<result>1</result >
<resultCode>000</resultCode>
</Response>

Data
Type
Int
String

Description
1 - Result Accept,
2 Result Rejected
000 Success
101 msisdn already
registered
102 invalid msisdn
402 Unknown subscriber
604 Timeout, System Busy
605 Error, System Busy
606 db error

Asterisk Call Processing

dahdi_channels.con
f 1: TE4/0/1 "T4XXP (PCI)
; Span
Card 0 Span 1"
(MASTER) HDB3/CCS/CRC4
ClockSource
group=0,11
context=cs_deposit
switchtype = euroisdn
signalling = ss7
channel => 2-31
group = 63

; Span 2: TE4/0/2 "T4XXP (PCI)

Card 0 Span 2"
HDB3/CCS/CRC4
group=0,12
context=cs_callback
switchtype = euroisdn
signalling = ss7
channel => 32,62
group = 63

E1 Line
Configuration

extensions.conf
[cs_deposit]
exten => _x.,1,Answer()
exten =>
_x.,n,agi(agi://localhost/cs_deposit.a
gi)

exten => _x.,n,Hangup

[cs_callback]
exten => _x.,1,Answer()
exten =>
_x.,n,agi(agi://localhost/cs_callback.
agi)

exten => _x.,n,Hangup

dialplan

AGI can run a Java application (on the same machine that runs Asterisk
or on a separate machine).
Combined with Java's multithreading support can build pretty fast AGI
scripts using this protocol.

Asterisk Gateway Interface

Asterisk Gateway Interface (AGI)

Means how application programmers can implement external

logics utilizing Asterisk.

- To perform advanced logic
- To communicate with databases
- Perform complex tasks that would be hard to do with Dialplan

Application level API, which means that application developed

using AGI are not bound by the Asterisk License and are not
required to be re-distributed with the source.
Very much similar to a CGI interface used by web server, where
communications between Asterisk and your AGI program is
performed via an STDIN/STDOUT interface.
Invoked from Dialplan (AGI() application)
exten => 123, 1, Answer()
exten => 123, 2, AGI(test.agi)
...

It allows the use of high level languages like Java, Perl, PHP and

Python to extend Asterisks functionality.

How to execute an AGI program from

the Asterisk dial plan?
Each item in an extension is of the form:
exten => extension-number,priority,application,arguments

To launch an AGI script the application is agi and the

argument is the filename of your script.

The script:
- must be executable
- must be located in /var/lib/asterisk/agi-bin
- must be specified complete with an extension

For example to run a Python script named test.agi then a

suitable extension item would be:

exten => 123, 1, Answer()
exten => 123, 2, AGI(test.agi)
...

Communicating with the Asterisk AGI

interface

Format for passing parameters to an AGI script is as follows:

AGI(script.agi, arg1, arg2, ...)

AGI script communicates with Asterisk by sending AGI

commands on standard output and receiving responses on
standard input.
The result typically takes this form:
<code> result=<result> [data]
where
code is an HTTP-like response code (200 for success, 5xx for error)
result is the result of the command (common values are -1 for error, and 0 for success); some
commands return additional name=value pairs in data, while some return a string value in parentheses
(especially "timeout" for a timed command.)

Code

Example result text

200

result=0

510

Invalid or unknown command

Command Not Permitted on a dead
channel
End of proper usage

511
520

Passing arguments to your AGI program

In order to pass arguments to your AGI program, you need to define

them in the extension.

In example, to launch an AGI program with a parameter would look like

so:
exten => 1,2,agi,test.php|${CALLERID}

In the above example, Asterisk will pass the environment variable $

{CALLERID} to the AGI program test.php

AGI script is also passed a number of environment variables which

point to file-system directories which contain Asterisk files

Asterisk Manager Interface

Asterisk Manager Interface

(AMI)
AMI enables a client program to connect to an Asterisk instance and

issue commands or read events over a TCP connection.

Systems integrators will find these resources useful to track channel

states.
AMI is built in a simple concept of a line protocol using key:value pairs

over TCP.
Allows external programs to control and monitor Asterisk
If you have lots of connections to AMI consider using Asterisk Manager

Proxy.

AMI protocol behavior

Before sending any commands to Asterisk, you need to

establish an AMI session

- The first line of a packet will have the key Action when sent from a client
- The first line of a packet will have a key Response or Event when coming from
Asterisk
- Packages can be transmitted in any direction after the authentication

The type of the packet is determined by the existence

of the following keys:

- Action: A packet sent from a client connected to AMI asking for a specific action. The
loaded modules determine these actions. A packet contains the action name and its
parameters.
- Response: The response sent from Asterisk to the last action sent from the client.
- Event: Data belonging to an event generated in the Asterisk core or by a module. When
a client sends packets of the Action type, a parameter named ActionID is included. Since the
order in which the responses sent from Asterisk cannot be predicted, ActionID is used to
correlate actions and responses.

AMI Information available for each of these event/action

types

The following is a short explanation of the information

available for each of these event/action types:
system: Actions and events related to Asterisk's core elements, such as SIP peers and
the Asterisk Database
call: Actions and events related directly to Asterisk's extension statuses, and call
progress and call control
log: The source documentation doesn't provide detailed information about the nature
of information provided by events of this type.
verbose: The source documentation doesn't provide detailed information about the
nature of information provided by events of this type.
command: This directive enables our connected user to send commands to the
Asterisk CLI interface
Agent: Actions and events related to Asterisk's queue applications
User: User events can be generated from the dialplan, using the UserEvent
application. Using user events are a valuable tool when developing applications that
incorporate dialplan, AGI, and AMI at the same time.

AMI Communication:

Asterisk

AMI
TCP
Sock
et
Servi
ce

Action:
Originate
Response:
Success
Event: Dial
Event:
PeerStatus
Event: DTMF
Event: Registry

PHP, JAVA,
C
Application

AMI Action packets

When you send an action packet to Asterisk, you can provide

some extra keys (e.g. called number).

You do this by passing key:value pairs after the Action.
It is also possible too pass channel and global variables to the

dial plan.
Action: <action type><CRLF>
<Key 1>: <Value 1><CRLF>
<Key 2>: <Value 2><CRLF>
Variable: <Variable 1>=<Value 1><CRLF>
Variable: <Variable 2>=<Value 2><CRLF>
...
<CRLF>

What language to use for AMI?

Selecting a programming language can be hard these days.
There are simply too many options like Java, PHP, Perl, C, C#,

Python, and several others.

Its possible to use AMI with any language that supports a socket or

telnet interface.

Thank You