Asterisk Based Implementation

and development platform

Need to communicate?? Asterisk is your answer.

Prepared by: Muhammad Shahzad

UCPK

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 2

Agenda

Asterisk
o What is Asterisk?
o What Does Asterisk Do?
o 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 How to execute an AGI program from the Asterisk dial plan?
o Communicating with the Asterisk AGI interface
o Passing arguments to your AGI program

Asterisk Manager Interface

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

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 3

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)

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 4

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
o
o
o
o
o
o
o

Drivers for various VoIP protocols and for PSTN interface cards.
Routing and call handling (incoming and Outbound calls).
Media management functions (record, play, generate tone, etc.).
Call detail recording for accounting and billing.
Transcoding (conversion from one media format to another).
Protocol conversion (conversion from one protocol to another).
Database integration.
Web services integration.

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 5

What Does Asterisk Do? (Cont)

o
o
o
o
o

LDAP integration for accessing corporate directory systems.

Single and multi-party call bridging.
Call recording and monitoring.
Integrated "Dialplan" scripting language for call processing.
External API in any programming language via Aaterisk 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.

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 6

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
Supports a large variety of VoIP and signaling

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 7

Asterisk Architecture

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 8

Asterisk Architecture
DAHDI

CLI

Applicati
on

Digital
card
drivers

SIP

IAX2

Asterisk
Core

Dialpla
n

Audio/Vid
eo
Codecs

Sys
Config
Drivers

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

H323

Manager
Interfac
e
Resourc
es

AGI

Strictly Confidential / Page 9

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
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 10

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

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 11

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
2010 Unified Communications Holdings Limited Group. All Rights Reserved.
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

Strictly Confidential / Page 12

Asterisk Architecture (Cont)

AGI Features:
o Provides a standard interface by which external programs may
control the Asterisk dialplan.
o Supports languages like Java, C#, PHP etco Can be located on different or on same sever running Asterisk.
o Full command over core functionalities of Asterisk.
o 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.
o Using Management API user can even manage Asterisk core from
AGI.
o User can play prompts from AGI, record files etc etc...

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 13

Asterisk as an Application based Platform

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 14

Block Diagram of Asterisk based Application

platform:
4

Services Request

Services Response

User

Response from ExternalAPI

Asterisk
Core
Dialplan

DB

ExternalAPI
Programmed API

AGI Script

3
HOST

Query to ExternalAPI

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Asterisk AGI Execution Flow

Diagram
Strictly Confidential / Page 15

Asterisk

Dialplan

AGI
Script

External
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
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 16

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

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 17

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..'.
DB & Provisioning
Server

External
API

Web Server

3rd party system

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 18

Communication b/w AGI and

ExternalAPI:

Asterisk
AGI

ExternalAPI
Request
<methodcall>
Response
<Response>

Request being
process
Process
completed

Asterisk AGI and ExternalAPI are communicate over TCP/IP socket

connections.

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 19

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>

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

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

Strictly Confidential / Page 20

Asterisk Call Processing

; Spandahdi_channels
1: TE4/0/1 "T4XXP (PCI)
Card 0.conf
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 =E1
63Line

[cs_deposit]
extensions.conf
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

Configuration

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.
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 21

Asterisk Gateway Interface

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 22

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 redistributed 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.
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 23

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)
...

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 24

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
200
510
511
520

Example result text

result=0
Invalid or unknown command
Command Not Permitted on a dead
channel
End of proper usage

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 25

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

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 26

Asterisk Manager Interface

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 27

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.

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 28

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.
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 29

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.
2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 30

AMI Communication:

Asterisk

AMI
TCP
Sock
et
Servi
ce

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

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

PHP, JAVA,
C
Application

Strictly Confidential / Page 31

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>

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 32

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.

2010 Unified Communications Holdings Limited Group. All Rights Reserved.

Strictly Confidential / Page 33

Thank You

2010 Unified Communications Holdings Limited Group. All Rights Reserved.