This area is for handsets, softphones, paging systems, or anything
else that could be considered an 'extension' in the classical PBX

Defining and editing extensions is probably the most common task
performed by a PBX administrator, and as such, you'll find you'll
become very familiar with this page. There are presently four types of
devices supported - SIP, IAX2, ZAP and 'Custom'. This page also
configures how voicemail is handled on a per-extension basis.

Adding a new extension

Phone Protocol
Pick one of SIP, IAX, ZAP or Custom

  • SIP is the Standard protocol for VoIP handsets and ATA's. The Session Initiation Protocol (SIP) is a signalling protocol, widely used for setting up and tearing down multimedia communication sessions such as voice and video calls over the Internet.
  • IAX is 'Inter Asterisk Protocol', a newer protocol supported by only a few devices (eg, PA1688 based phones, and the IAXy ATA)
  • ZAP is a hardware device connected to your Asterisk machine - Eg, a TDM400, TE110P.
  • Custom is a 'catch all', for any non standard device, eg
    H323. It can also be used for "mapping" an extension to an "outside"
    number. For example, to route extension 211 to 1-800-555-1212, you
    could create a custom extension 211 and in the "dial" text box you
    could enter: Local/18005551212@outbound-allroutes

Extension Number
This must be unique. This is the number that can be dialled from any other extension, or directly from the Digital Receptionist if enabled. This

may be any length, but conventionally a three or four digit extension is used.

CID Num Alias The CID Number to use for internal calls, if different from
the extension number. This is used to masquerade as a different user. A
common example is a team of support people who would like their internal
callerid to display the general support number (a ringgroup or queue).
There will be no effect on external calls.

SIP AliasIf you want to support direct sip dialing of users internally
or through anonymous sip calls, you can supply a friendly name that can
be used in addition to the users extension to call them.

Secret, aka 'Extension Password'
This is the password used by the telephony device to authenticate
to the Asterisk server. This is usually configured by the administrator
before giving the phone to the user, and is usually not required to be
known by the user. If the user is using a soft-phone, then they'll need
to know this password to configure their software.

very important to set this to 'yes' if you want to be able to use
your phone behind a nat firewall seperate from the lan that your
asterisk box is on.

disallow any codec you do not want to use. common setting for this
if you want to make sure a device only uses the codec set in the allow
section is "all" (without the quotes).

allow a codec of your choice. primarily as an example i would use
"g729" or "GSM" (without the quotes), only one codec can be set here.
This is usefull if used with the disallow option set to "all" and you
set the definitive codec you want to use on allow, garunteing that you
will use that codec.

This option allows you to set what mailbox you would like to use.
Normally you would use 'your extension'@device . but if you want to say
have an extension's phone's light or dial tone indicate when a
different box has voicemail you can set it to 'extension vm'@device. so
say extension 1002 wants to know when 1001 has vm, then set this to
1001@device on 1002's mailbox setting.

Record Incoming
Option to record the calls received on this extension. There are three options:

  • Always
  • Never
  • On-Demand (User can dial '*1' to enable whilst in a call)

Record Outgoing
Same as above but for outgoing calls

Voicemail and Directory
Selecting 'Disabled' turns off voicemail for this extension totally, and these further options are hidden.

Voicemail Password
This is the password used to access the voicemail system (*98). It
can be changed by the user when they log into their voicemail (after
logging in, they dial 0 then 5).

Email Address
The address that voicemails notifications will be sent to

Pager email address
This email address will be sent a small message notifying of voicemail messages, suitable for an email-to-pager service.

Play CID
Read back caller's telephone number prior to playing the incoming
message, and just after announcing the date and time the message was

Play Envelope
Envelope controls whether or not the voicemail system will play
the message envelope (date/time) before playing the voicemail message.
This settng does not affect the operation of the envelope option in the
advanced voicemail menu.

Delete Vmail
If set to "yes" the message will be deleted from the voicemailbox
(after having been emailed). Provides functionality that allows a user
to receive their voicemail via email alone, rather than having the
voicemail able to be retrieved from the Webinterface or the Extension

CAUTION: You must have email attachment set to yes if you
don't want your voicemail system to email you a notification saying
'You have a voicemail' and then immediately delete the voicemail. Make sure you've fully tested voicemail-to-email before you turn this on. See Email Problems for hints.

Taxonomy upgrade extras: 


shahab.sabir's picture

Making an extension:
To create an extension first select the type of the trunk. i.e. SIP, IAX2, ZAP or Custom. I selected the SIP and click on the submit button to confirm.
Then click on the add extension and a new pop-up window will open. Add the extension numbers you want to assign to the users. (I gave 2000 and 2001).For simplicity I gave the same passwords which are used to troubleshoot configuration of the set and as well as for voicemail. You can also give passwords of your own desire. Its up to you. The dtmfmode module was selected as rfc2833 (A protocol for signaling between the subscriber and the host).
Click on the red bar on the top of the screen every time you create a new extension.
If you want to make this extension as a remote extension you will have to change the configuration under the Device Options. I.e. Nat: Yes: Nat to never
Then I give the display names as per users.
I left the extension options blank for my ease and disabled voice mail. After that click the submit tab to create the extension.
Allow Anonymous Inbound SIP Calls:
Set this to (yes), if not set to yes all inbound unidentified SIP calls will not be accepted.
Dial Command Options:
In the Asterisk dial command options you may customize your preference to the way Asterisk behave. For example if the caller wants to hear music instead of a standard dial tone you can simply replace “r” with “m”.
Some main dial command options are given below.

A(x): Plays the announcement to the called party, using “x” as a file
C: resets the CDR for this call
D: Allows the calling user to dial a 1 digit extension while waiting for a call to be
answered, Exit to that extension if it is defined in the EXITCONTEXT variable.
D ([called][:calling]): Sends DTMF string to the called and calling party before the call
is bridged.
f: Forces the caller id of the calling channel to be set as the extension associated
with the channel using dial plan “hint”.
g: Proceeds with dial plan execution at the current extension if the destination
channel hangs up.
G (context^exten^pri): If the call is answered, transfer both parties to the specified
priority. Usually an extension or a context.
h: Allow the called party to hang up by “*”.
H: Allow the calling party to hang up by “*”.
i: Jump to priority n+101 if all the requested channels were busy
L (x [: y][:z]): This option limits the call to ‘x’ ms. Play a warning when ‘y’ ms are left.
Repeats the warning when ‘z’ ms are left. It has special features; Plays sound to
the caller and Callee, a play file when time is up and begins and also plays
warning (default: that time is up).
m ([class]): Provides hold music to the calling party until the call is answered.
n: It saves the screen/privacy mode. Introductions are to be saved in the priv-
callerintros directory.

N: It specifies that caller id is present do not screen the call.
p: Screen mode, privacy mode without memory.
r: Indicates ringing to the calling party. Pass no audio to the calling party until the
called channel has answered.
S(x): Hangs up the call after ‘x’ seconds after the called party has answered the call.
t: Allow the called party to transfer the calling party by sending the DTMF
sequence defined in features.conf.
T: Allows the calling party to transfer the called party by sending the DTMF
sequence defined in features.conf.
w: Allows the called party to enable recording of the call.
W: Allows the calling party to enable recording of the call.
Extension Numbers to avoid:
They are given below.
200 Park Notify
300-399 Reserved for speed dial
666 Reserved for Fax dialing
70-79 Reserved for calls on hold
700-799 Reserved for calls on hold
7777 Reserved extension for incoming calls simulation
Follow Me:
To activate the follow me module click on the follow me tab and do as given under. Choose the extension number to which you want to assign the follow me option. A new window opens with the modules given below. Enter the following information to the appropriate module.
Ring Strategy: Enter ‘hunt’ >> to call the numbers in sequence
Alert info: Blank
Extension List: Enter the extension followed by the mobile number (Note that the mobile number should end with ‘# ‘sign. For example (2000) (03335056537#)
CID name prefix: Blank
Ring Time: 40 sec
Announcement: None
Destination if no answer:
Follow Me (My extension) 2001
Core (voice mailbox 2001)
Time conditions (Normal)
Ring Group (Ring group 10)
IVR (Main)
Custom App (Blank)
Every time my extension is called, Asterisk will try to connect to extension 222 and if no answer, it will call my mobile. If still no answer, it will drop to my mailbox.
Rings groups:
A ring group is a group of extensions that will ring when there is an external incoming call. You can even put your mobile number in this list if you want to. e.g. 03335056537#. For mobile number to work properly you will have to set up the appropriate route and trunk.
I created a single ring group (Ring Group 10) as follows
Group description: All Phones
Ring Strategy: Ring All
Extension List: (2000) (2001) (03335056537#)
CID name path: Blank
Ring Time: 40 sec
Announcements: None
Destination if no answer: Core (voice mail 2000)
Direct Inward System Access
Used in PSTN to VoIP gateways
Allows you to dial in from outside to the Asterisk switch (PBX) to obtain an internal system dial tone. You can place calls form it as if they were placed from within the system. Normally this is accomplished by digital receptionist and enter the unannounced option number known only to selected callers. The callers enters the password followed by a ‘#’ sign, if it is correct he gets the system dial tone for an external call.
Do use DISA click on the DISA module and enter the following information in the new window.
PIN: Password
Response Timeout: 10sec
Digit Timeout: 5sec
Caller ID:
Context: From Internal
Keep the rest of modules as default for simplicity.
DISA will work properly if you have setup your digital receptionist. You can enter the password followed by a ‘#’ sign and the number you wish to dial without waiting for the dial tone.
Dial Pattern:
These are parts of outbound routes. They act like a filter for matching numbers dialed with trunks. The various types of dial patterns are given below.
Secret Refers to any digit between 0 and 9
N: Refers to any digit between 2 and 9
Z: Any digit that is not zero e.g. 1 to 9
[Various]: Matches only one number within the brackets e.g. [06-68*#]
. : Must match something
|: Lets you dial 0 but not sending to the trunk
It is a telephone service line that is used to make an external call, e.g. PTCL line that you have at home is a trunk or a voice service provider (VSP) to which you have signed is a trunk. To make external calls (VoIP or PSTN) you should have at least one trunk. You can have many trunks at a same time. i.e.
Trunk A: Best rate for local calls, expensive for mobile calls and not so great for
international calls.
Trunk B: Great rate for international calls.
Trunk C: Good mobile rate and 500 numbers that other do not.
A properly planned route will direct the phone calls to the appropriate trunk that will provide maximum efficiency and saving. E.g. When you call a mobile number Asterisk will route your call via Trunk C, for local call to Trunk A and for international call it will route to Trunk B.
To create a new trunk using free PBX, select setup tab and then select the trunks options from the vertical menu on the left.
First of all in General Settings enter
Outbound Caller ID: “Insert your Name”
Must include “” and <>.

gwhosting's picture

i'm sure i'll find this but figured i would ask, how do i get an extension to go to for say my home phone, mobile, then to my friend's mobile, and then her home, and then say voicemail?

GW Hosting, Your Dedicated Home On The Web:

sliderip's picture

I have FreePBX 2.5.1 and Aastra 57iCT setup as a remote extension. It works fine except i can not update the phone off TFTP server. I opened the firewall port on the server. I can tell from the Aastra web interface that it does c the updated firmware but for some reason when it tries to update it fails to actually download it.

I think it may be due to some for firewall issue on either end may be, any help is welcome?


fskrotzki's picture

Please do not post questions in the documentation sections as they will probably not get answered here. Please re post your question in the forum area where people go to look and help those with issues.

As for tftp and firewalls please realize that tftp uses a udp packets one on port 69 and the rest are on random high port numbers, this is totalt different from FTP which uses TCP packets and fixed ports by default. Normally it's not possible to open a firewall for tftp traffic going out unless your firewall has tftp support designed into it.

jervin's picture

On this, the extensions page (http://www.freepbx.org/support/documentation/module-documentation/extensions), I see near the bottom where it says "See Email Problems for hints". Where might I find the "Email Problems" section? I did a search and didn't find it.

John F. Ervin
Central Florida TeleSource