<- ...Back> Continue... ->

Codecs

Codec is a frankenword (portmanteau) which describes a device or program capable of

performing transformations on a data stream or signal. Essentially, codecs can both put

the stream or signal into an encoded form (often for transmission, storage or encryption)

and retrieve, or decode that form for viewing or manipulation in a format more

appropriate for these operations. Codecs are often used in videoconferencing and

streaming media solutions.

[wikkipedia]

What this means to you and me is that codecs compress data, allow you to transmit the

compressed data which is then uncompressed at the receiving end. This should have sent

some bells ringing in your head. Yes, if I compress something with ASC (“Andy's Special

Codec”) and you don't have that installed, then you wont be able to decompress it. The

same applies for Asterisk, and all other VoIP devices.

	Different codecs have different compression ratios resulting in different bandwidth requirements. Generally the higher the compression the more cpu power required to compress, and sometimes decompress. In most cases this means: Higher compression = More CPU = Lower Bandwidth Lower compression = Less CPU = More Bandwidth So the more bandwidth you have, the less need for a higher compression ratio.

Asterisk has wide support for codecs, on your system you can see how quickly your

particular Asterisk machine can translate from one codec to another by using the

command:

show translation

this will result in something like

This is a simple table, you read your from codec down the left and your to codec along

the top (actually is doesn't matter which way you do it). For example on my test

machine is takes 299 milliseconds to translate from GSM to g723 – diabolical! Try it on

your machine. Don't worry if, for example, g729 is just dashes (-) g729 is a codec you

have to pay for, it it shows dashes, you don't have it installed.

Bandwidth Requirements for Several Common VoIP Compression Algorithms

Codec	Codec Bit Rate (Kbps)	Nominal Ethernet Bandwidth (Kbps)
G.711	64	87.2
G.729	8	31.2
G.723.1	6.4	21.9
GSM	13.2	N/A
iLBC	13.3	N/A
G.723.1	5.3	20.8
G.726	32	55.2
G.726	24	47.2
G.728	16	31.5

oh323.org provide a spreadsheet showing more detailed information, which also allows

you to recalculate based on the packet overhead. It can be found here

http://www.terracall.com/bandwidth.xls At the end of this document you'll find at the

calculations based on an overhead of 40, just in case you have no Internet access while reading this.

Channels

Channels relate to the technology (protocol) they implement, for example the channel SIP (chan_sip.so) is used to register SIP phones, register with SIP service providers and provide the communications mechanisms for Asterisk to be able to 'talk' SIP. Just a few pages back we talked about the Dial command and contacting a SIP device, but it doesn't stop there. Asterisk supports a number of different technologies (channel types) and can convert between them. What this means is you could have a SIP phone and an IAX2 phone connected to an Asterisk PBX and ring the SIP phone and talk away to your heart's content from the IAX2 phone and vice-versa, all automatically, without you having to do anything special.

This also means that you can do things like locate Asterisk boxes at remote locations providing virtual E1 or T1 connections.

Common Asterisk Channels

IAX2/IAX Asterisk's own protocol, traverses NAT easily, uses a single

port for control and audio. IAX is still usable, but it is recommended that only IAX2 is used, indeed IAX is by default

not compiled – Stick with IAX2.

SIP Session Initiation Protocol, and industry standard protocol

becoming very popular indeed. Uses different ports for

control and audio. NAT can be tricky.

ZAP Channel for Zaptel hardware, Digium boards (FXO/FXS/PRI).

Skinny Cisco protocol, reverse engineered by members of the Asterisk

community.

MGCP Media Gateway Control Protocol, developed by Telecordia and

Level 3 Communications. Was designed to compete with H323

and like H323 a bit long in the tooth. Still used in new

deployments.

H323 Must be built using H323 libraries, not a solid implementation

in Asterisk.

OSS/ALSA Sound card channel drivers, allow dialing from the console.

BTP Bluetooth presence channel, automatic routing based on

the presence (or absence) of a Bluetooth device such as a

mobile (cell) phone.

With the exception of H323 and BTP all the above protocols are built and installed automatically during the compilation/install process.

	When dialing using the Dial command you specify the technology you want to use for example: Dial(IAX2/guest@an-iaxprovider.com) Dial(SIP/1000) Dial(ZAP/g1/${EXTEN})

In the next section we'll take a look at some of the most common commands you'll probably use in your dialplan.

Common Dialplan Commands

Asterisk has many built in commands that you can use within the dialplan, in this section we'll cover the ones that you'll probably end up using the most, enabling you to put together complex dialplans reacting to different events. This section is not supposed to be an exhaustive list of the commands available, but is a selection of the most common commands that you will probably end up using, most of the time.

	You can find a list of the available applications in Asterisk by using the command show application (with a space after application) and then hit the tab key while at the Asterisk CLI prompt. Detailed information about each application can be seen by using show application <application name> eg: show application dial while at the Asterisk CLI prompt.

Answer

Answer()

Answers a ringing channel, if the channel has already been answered it does nothing.

Return code

Returns 0 unless answering the channel fails in which case returns -1.

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

Background

Background(filename[|options[|langoverride]]):

Plays a given file, while waiting for the user to enter an extension to jump to. Background is often used in simple menus such as:

Press 1 for sales, 2 for support ...

You should set the timeout using ResponseTimeout(seconds) after which the process will jump to the 't' extension – if it exists. The timeouts do not start until the last Background application has ended.

Options, skip or noanswer, (optional) may also be included following a pipe symbol.

The skip option causes the playback of the message to be skipped if the channel is not in the up state (i.e. it hasn't been answered yet). If skip is specified, the application will return immediately should the channel not be off hook.

Unless the 'noanswer' option is specified, the channel channel will be answered before the sound is played. Not all channels support playing messages while still hook.

The 'langoverride' (optional) may be a language to use for playing the prompt which differs from the current language of the channel

Return code

Returns -1 if the channel was hung up, or if the file does not exist, otherwise returns 0

Example

[my-menu]

exten => s,1,Answer

exten => s,2,ResponseTimeout(8)

exten => s,3,Background(menu-main-sound)

exten => 1,1,Dial(SIP/SalesPhone)

exten => 2,1,Dial(SIP/SupportPhone)

exten => t,1,goto(s,3)

The example answers the line, sets the timeout to 8 seconds and then plays the main-menu-sound file. At any time during the playback of the sound file, or in the 8 seconds after it the caller may press 1 or 2 to dial a phone. If there is no response from the caller after 8 seconds, the t extension if executed, which in this case simply plays the menu again.

Dial

Dial(technology/resource[&technology2/resource2...][|timeout][|options][|URL])

Requests a new channel, places an outgoing call to the specified destination(s) and bridges (links) the two channels when the remote side answers. If multiple destinations are specified the first to answer is bridged with the calling user.

Technology (Required) specifies the channel driver to use, for example SIP, IAX2, ZAP.

Resource (Required) specifies the remote end, for example a registered phone, gateway server or service. The resource may be a remote machine defined via either an entry in the config file (for the technology) or on the dial line

Timeout (Optional) is the number of seconds to ring before giving up, the general calculation for seconds to rings is:

Seconds / 4 = Rings

although there may be slight variations based on the technology used.

Options (Optional) specifies a list of required functional enhancements to use. The options are case sensitive, and may be stacked, i.e. you may have multiple options

Option	Description
t	Allow the called user transfer the calling user by hitting #.
T	Allow the calling user to transfer the call by hitting #.
f	Forces callerid to be set as the extension of the line making or redirecting the outgoing call. For example, some carriers don't allow callerids from other extensions then the ones that are assigned to you.
r	Indicate ringing to the calling party, pass no audio until answered. Only to be used if for some reason callers can't hear ringtone. This is a dumb option, if the destination line is busy the caller will hear ringing then the busy tone.
m	Provide hold music to the calling party until answered.
M(x)	Executes the macro (x) upon connect of the call.
h	Allow called user to hang up by hitting *.
H	Allow calling user to hang up by hitting *.
C	Reset call detail record (CDR) for this call.
P[(x)]	Enable privacy mode, using 'x' as database if provided.
g	Continues on in context if the destination channel hangs up. Normally if the remote end hangs up both ends of the call stop.
A(x)	Play an announcement to the called party when answered, using x as the file.
S(x)	Hangup the call after x seconds AFTER called party picked up.
D([digits])	Send DTMF digit string after called party has answered but before the bridge. (w=500ms sec pause). Useful for automatically entering pin codes or to make 2 stage dialing appear as one stage dialing.
L(x[:y][:z])	Limit the call to 'x' ms, warning when 'y' ms are left, repeating every 'z' ms. Only 'x' is required, 'y' and 'z' are optional. The following special variables are optional: Play sounds to the caller only: LIMIT_PLAYAUDIO_CALLER Valid values are yes|no (default yes). Play sounds to the called user only. LIMIT_PLAYAUDIO_CALLEE Valid values are yes|no File to play when time is up. LIMIT_TIMEOUT_FILE File to play when call begins. LIMIT_CONNECT_FILE File to play as warning if 'y' is defined. LIMIT_WARNING_FILE 'timeleft' is a special sound macro to auto-say the time left and is the default.

URL is an optional url to send to the remote part. Not all devices support this feature. The dial command will attempt to dial using the technology and resource provided, if the timeout ocurrs then then next priority is executed. If the dial returns busy then the dial command will jump to priority + 101 – if it exists.
Examples

A simple dial:

exten => 100,1,Dial(SIP/1234)

Dial multiple destinations, ringing for a maximum of 60 seconds. Force the callerid to be the extension and allow the calling user to transfer the call using the # key:

exten => 200,1,Dial(SIP/1234&IAX2,60,fT)

Dial a single destination, ringing for a maximum of 30 seconds, playing music instead of ringing. Force the callerid to the be the extension and allow the calling user to transfer the call using the # key:

exten => 300,1,Dial(SIP/1234,30,mfT)

Dial a single destination, ringing for a maximum of 20 seconds. Limit the call length to 60 seconds, warning the caller when only 20 seconds remain:

exten => 200,1,Dial(SIP/1234,20,L(60000:20000))

Dial a remote server:

exten => 100,1,Dial(SIP/1234@somenetwork.com)

Dial a pattern matched extension, ringing for a maximum of 20 seconds. if that fails, dial a remote server – note the use of ${EXTEN} to indicate the number dialed:

exten => _XXXXX.,1,Dial(IAX2/${EXTEN},20)

exten => _XXXXX.,2,Dial(SIP/${EXTEN}@somenetwork.com)

Echo

Echo()

Starts an echo test, where received audio is sent back to the sender. Allows one person to perform the Marco Polo test on an Asterisk server.

Example

exten => 100,1,Answer

exten => 100,2,Wait(1)

exten => 100,3,Playback(demo-echo)

exten => 100,4,Echo()

exten => 100,5,Hangup

The example answers the line, waits one second, plays back a sound file describing the echo test and then begins the echo test.

Goto

Goto([[context|]extension|]priority)

Jump to another context (optional), extension or priority within the dialplan

Example

exten => 100,1,Goto(anothercontext,200,1)

If context is omitted then the current context is used.

Gotoif

GotoIf(Condition?label1:label2)

Jump to another priority (label1) within the dialplan if condition is met, otherwise jump to label2

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

The example sets a variable to 0 then proceeds in the dialplan, at some point it increments the variable by one. Priority 8 tests to see if the variable is less than 4, if it is it jumps to priority 5 of the current extension, if not it jumps to priority 9.

Hangup

Hangup()

Unconditionally hangup a line, terminating a call.

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

NoOp

NoOp()

Pronounced as No Op (not noop), this application does errm, nothing. NoOp actually means “No Operation” - i.e. do nothing. This isn't strictly true, NoOp can do useful things, it can act as a spacer in extension priorities and it can be used to print variables on the console.

Example

exten => 100,1,NoOp(${CONTEXT})

would display the current context on the console when extension 100 was called.

Playback

Playback(filename[|option])

Plays the specified sound file (you should omit the file extension). Playback will play the whole sound file, and when complete, return control to the dialplan. Even though the Playback command will pick up the line if it has not been answered it is much more useful to answer the line prior to issuing the Playback command, then issue a wait, simply because it takes time for a channel to be picked up. If you do not answer and then wait, you may find the beginning of the sound file is not heard by the caller.

By default sound files are stored in the /var/lib/asterisk/sounds directory. The default path can me changed by modifying /etc/asterisk.conf.

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

SetVar

SetVar(var=val)

Sets the variable var to value val. The variable can then be referred to in the dialplan by using ${var} where var is the name you gave the variable. These variables only exist for the duration of the call and are automatically destroyed when the call is hung up.

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

VoiceMail

VoiceMail([s|u|b]mailbox[@context][&mailbox[@context]][...])

Starts the process of leaving a voice mail message for the extention specified by mailbox, in addition you may specify a context located within /etc/asterisk/voicemail.conf – if the context is omitted, then the context “default” is used. The mailbox to be used may be preceded with one of the following options

Option	Meaning
s	Skip introductory message explaining how to leave a message
u	The message “The person at extension <extension> is unavailable” will be played to the caller.
b	The message “The person at extension <extension> is on the phone” will be played to the caller.

Notes

If the caller presses 0 at the prompt and an extension, o (lower case letter O) exists then the caller will jump to that extension.

If the caller presses * at the prompt and an extension, a exists then the caller will jump to that extension.

If there is no entry in voicemail.conf for the extension specified and priority +101 exists then the call will jump to that priority.

If more than one mailbox is specified then the messages played to the caller are those for the first mailbox in the list.

Examples

[my-users]

exten => 100,1,Dial(SIP/1234,20)

exten => 100,2,VoiceMail(u1234)

exten => 100,3,Hangup

exten => 100,103,VoiceMail(b1234)

exten => 100,104,Hangup

exten => o,1,Playback(calling-operator)

exten => o,2,Dial(IAX2/operator)

VoiceMailMain

VoiceMailMain([[s]mailbox][@context])

Starts the voice mail system and allows the caller to retrieve and listen to messages for the voice mail specified by mailbox, in addition you may specify a context located within /etc/asterisk/voicemail.conf – if the context is omitted, then the context “default” is used.

Notes

If the mailbox is omitted then the user will be prompted to enter their voice mail number

If a mailbox is specified then the mailbox to be used may be preceded with one of the following options

Option	Meaning
s	The user will not be asked to enter their password
p	The user input is appended to the supplied mailbox resulting in <mailbox><digits dialed> being used as the mailbox to use.

Examples

Access voice mail account 1234 without asking for a password

exten => 1010,1,VoiceMailMain(s1234)

Access voice mail asking the user for a mailbox number and a password

exten => 1012,1,VoiceMailMain()

Wait

Wait(sec)

Pauses execution of the dialplan for sec seconds

Example

exten => 1234,1,Ringing

exten => 1234,2,SetVar,"COUNTER=0";

exten => 1234,3,Answer

exten => 1234,4,Wait(1)

exten => 1234,5,SayUnixTime(,CET,ABdY 'digits/at' IMp)

exten => 1234,6,SetVar,"COUNTER=$[${COUNTER} + 1]";

exten => 1234,7,Wait(1)

exten => 1234,8,GotoIf,"$[${COUNTER} < 4]?5:9"

exten => 1234,9,Playback(vm-goodbye)

exten => 1234,10,Hangup

	Never use spaces between parameters in dialplan commands unless quoting. For example Goto(mycontext, 199, 1) would attempt to find extension “ 199”, priority “ 1” in context mycontext. It would fail since extensions can not start with a space character.

<- ...Back> Continue... ->