User Manual

User Manual

Initialize System

At minimum, you will need to create a root user, an account, and an administrator for the account. Each account can be thought of as a seperate PBX, in the sense that it has its own set of endpoints and extensions, and there should be no bleeding of anything between the accounts.

If you are the network/voip admin at Foo, Inc and setting up a local PBX for the company, you will probably only want one single account called 'foo'. On the other hand, if you are a voip consultant and running a single WikiPBX server and hosting multiple clients, you will want seperate accounts for each of your clients.

Create Root User

  • Click [Add Root] and add a root user.
  • Login as root

The root user has a different set of menus. The main function of the root user is to manage accounts and the server as a whole.

In order to start adding extensions, you will first need an account and an account admin.

Create account + account admin

  • Login as root
  • Create a new account and an account admin for that account. (must use different email as root)

WikiPBX will restart FreeSWITCH at this stage. In the future this will hopefully be changed to send a socket message telling FreeSWITCH to reload its configuration.

Create endpoints/extensions

  • Logout as root
  • Login as the account admin
  • Create endpoints and extensions

Registering SIP Endpoints

An 'endpoint' is just a generic word for a 'phone', which covers hardphones, softphones, etc. Also referred to as 'device' in some contexts.


  • Click Endpoints / Add
  • Choose a User ID / Password
  • It is recommended to add an Extension for the endpoint

Configure Endpoint

Sipura Example

The following instructions are geared towards a Sipura endpoint, though should be useful for any type of endpoint, only the terminology might require a little translation.

Please see Configuring Softphones for the basic information. ''Please play close attention to the Firewall/STUN issues'', because FreeSWITCH is a bit more strict than Asterisk in this regard.


As far as WikiPBX is concerned, the only thing you should really pay special attention to is the '''Proxy''' field. The value you put in this field depends on what [[account domain|domain]] you entered for the acccount.

  • If [[account domain|domain]] is blank, then you must configure the '''Proxy''' field with the ip address in the [[account external sip|external-sip-ip]] field.
  • If [[account domain|domain]] has, then you must configure the proxy field to be, where sip-port is the [[account sip port|sip-port]] for the account.
User ID

Enter the User ID you entered when adding endpoint in WikiPBX.


Enter the Password you entered when adding endpoint in WikiPBX.

Auth ID

Set '''Use Auth ID''' to No and leave '''Auth ID''' blank.

XLite Example

<font color="red">The following instructions did not work</font>

  • Download the xlite for Windows.
  • Install and reboot
  • Start application. When SIP accounts window pops up, click Add
  • Display Name: Your Name
  • User id: example .. 200
  • Password: example 1200
  • Authorization user name: blank
  • Domain: Enter the domain you entered in wikipbx account config, eg,
  • Sound outbound via proxy
  • Enter the domain you entered in wikipbx account config, eg,, followed by the port if its not 5060. Eg, <font color="red">Try leaving this field blank if you are having problems registering your SIP account</font>
  • Close dialog
  • Will say "registering .. " followed by Ready on top left of lcd screen


  • There is an 'indicator icon' on the GUI under the endpoints listing page, however this is unfortunately not reliable.
  • Depending on your endpoint and how its configuration, the presence of a dialtone can indicate successfull registration.
  • From the Endpoints / Manage, click the phone icon and WikiPBX will dial the endpoint and playback an audio file.


If it doesn't work, you will need to use the FreeSWITCH console, as WikiPBX does not currently provide any help.

Configuring Gateways

Gateways allow you to 'bridge out' to the PSTN, as well as receiving incoming calls from the PSTN, depending on what services you have ordered.

Free World Dialup Example

Free World Dialup is a popular free service that lets you call anyone on the network for free. Here are the instructions on how to get calls working both ways.

Add Gateway

First, add a gateway called 'fwd' using the following parameters, leaving the rest as default:

  • '''username:''' <fwd number>
  • '''password:''' <super secret password>
  • '''realm:'''
  • '''proxy:'''
  • '''register:''' true

where <fwd number> is your assigned free world dialup number, for example: '''724316'''

Wait a few seconds, then go to the freeswitch console and type

sofia status gateway fwd

And verify the state is REGED

Dialout Test

For testing that dialing out of the fwd gateway works, add an extension

  • Extension #: ^613$
  • Description: echo
  • Dialplan XML: <action application="bridge" data="sofia/gateway/fwd/$1"/>

And then call extension 613, and you should hear the echo test and have 2 way audio.

NOTES on NAT: This should work even if your freeswitch/wikipbx installation is behind a NAT (network address translation), such as a wireless router you typically find on home networks. The reason it works is because FWD is very lenient, and even though unroutable internal LAN ip addresses/ports are sent in the SIP headers, it ignores these and just looks at the incoming connection's ip and port.

Outgoing Extension

To dial out of fwd for any six digit extension, add an extension to your dialplan:


with dialplan xml:

<action application="bridge" data="sofia/gateway/fwd/$1"/>

Then try calling another fwd user.

Incoming Extension

Add an extension equal to your fwd dialup number, for example '''724316''' that was used in above example, so your extension # should be:


And for the dialplan XML, you can add anything you like. Perhaps for an initial test, add

<action application="echo"/>

and then after this works you can replace it with a bridge command that calls one or more endpoints.



The basic syntax is:

<action application="set" data="vmaction=record">
 <action application="python" data="wikipbx.ivr.voicemail">

This will invoke the voicemail IVR which will prompt the caller to record a voicemail. A database record will be stored in the database, which will hold a path to the actual recording file, stored on the filesystem. By default, all administrators of the account will receive a copy of the voicemail.

To force it to only deliver to a specific web user, set the web user's email address before invoking the voicemail IVR:

<action application="set" data=""/>
 <action application="set" data="vmaction=record">
 <action application="python" data="wikipbx.ivr.voicemail">

Dial an extension, fallback to voicemail

Specific Web user voicemail

Because the <tt>mailbox</tt> variable is set to a particular web user, the voicemail will be stored in that particular user's voicemail inbox.

<action application="set" data="call_timeout=20"/>
<action application="set" data="continue_on_fail=true"/>
<action application="set" data="hangup_after_bridge=true"/>
<action application="set" data=""/>
<action application="bridge" data="sofia/test/4761%"/>
<action application="set" data="vmaction=record"/> 
<action application="python" data="wikipbx.ivr.voicemail"/>
All web users' voicemail

If no web user is specified, each Admin web user will receive a copy of the voicemail in their inbox.

<action application="set" data="call_timeout=20"/>
<action application="set" data="continue_on_fail=true"/>
<action application="set" data="hangup_after_bridge=true"/>
<action application="bridge" data="sofia/test/4761%"/>
<action application="set" data="vmaction=record"/> 
<action application="python" data="wikipbx.ivr.voicemail"/>

Playback via Phone

The voicemail can be listened to via the web interface as well, by clicking the email address under the Voicemail section on the left hand toolbar, then clicking the speaker icon.

The following instructions cover what is involved for setting up a phone extension that can be called to listen to voicemail messages.

Set mailbox ID / password

Since its not possible to enter the web user's email address via phone, a new 'mailbox id' must be invented in order to type it in via phone.

  • Login as admin user
  • Go to Web Users / Manage
  • Click the Web User you want to setup voicemail phone access for
  • Set the Mailbox field to something easy to remember. For example, if the user's name is Bob, perhaps set this to 262
  • Unless the web user password is already numeric, you will need to enter a numeric password for the vm_password field.

Create an extension

  • Login as admin user
  • Go to Extensions / Add
  • Choose 'voicemail player' from pulldown and click Plus icon

The extension XML will look like:

<action application="set" data="vmaction=play"/>
 <action application="python" data="wikipbx.ivr.voicemail"/>

Example Extensions

Dial a local endpoint and remote phone number simultaneously

<action application="bridge" data="sofia/gateway/voicemeup/12104400113,sofia/test/4761%"/>


  • Remote phone via 'voicemeup' gateway: sofia/gateway/voicemeup/12104400113
  • Local endpoint: sofia/test/4761% where 'test' is the name of your account

Dial out of a gateway for 1800 numbers

Set the destination number to:


And the action XML to:

<action application="bridge" data="sofia/gateway/voicemeup/$1"/>

Where 'voicemeup' is the name of a valid gateway on your system.

Dial out of a gateway for all USA numbers

Set destination number to:


And the action XML to:

<action application="bridge" data="sofia/gateway/voicemeup/$1"/>

Where 'voicemeup' is the name of a valid gateway on your system.

Connect to an IVR

<action application="python" data=""/>

Where '''foo''' is the name of your account

You can also set variables before connecting to the IVR, which the IVR will be able to 'see'

<action application="set" data="foo=bar"/> 
  <action application="python" data=""/>

Now when the IVR is called, it will see a variable called ''foo'', with the value of ''bar''


<action application="echo"/>


<action application="conference" data="freeconf"/>

The value in data defines the ID of the conference, which is created on the fly and no other configuration is necessary.

Play audio file

<action application="playback" data="/var/lib/wikipbx/soundclips/welcome_echo.wav"/>

Speak TTS

<action application="speak" data="cepstral|william|hello world"/>

Where ''cepstral'' is the name of the speech module, ''william'' is the name of the voice (however, if you dont know it, just use anything like 'yoda' and it will find the default voice). ''hello world'' is what will be spoken into the call.

Transfer to another extension

<action application="transfer" data="0"/>

Transfers to extension 0

Bridge to external extension

<action application="bridge" data="sofia/test/"/>

Example IVR's


Hello World

from freeswitch import *

def handler(uuid):
    session = PySession(uuid)
    session.set_tts_parms("cepstral", "william") 
    console_log("INFO", "Hello, world\n")
    session.speak("Hello World")

Time-based Routing

from freeswitch import *
import datetime

def handler(uuid):
    if not uuid:
        console_log("info", "\nNo uuid given\n")
    session = PySession(uuid)
    session.set_tts_parms("cepstral", "william") 
    session.speak("Hello, welcome to foo.")
    now =
    if now.hour >= 9 and now.hour <=17:
        session.speak("Connecting your call to the first available operator")
        session.execute("execute_extension", "4769 XML default")
        session.speak("Sorry, but nobody is available, connecting you to voicemail")   
        session.execute("python", "wikipbx.ivr.test.voicemail")
        session.speak("Sorry you have called after hours, bridging to voicemail")
        session.execute("python", "wikipbx.ivr.test.voicemail")
        session.speak("Goodbye and thank you for calling foo")

Playing a soundclip

import os

from freeswitch import *
from wikipbx.wikipbxweb.models import *

def handler(uuid):
    if not uuid:
        console_log("info", "No uuid given")
    session = PySession(uuid)
    session.set_tts_parms("cepstral", "william")
    account_id = session.getVariable("account_id")
    account = Account.objects.get(pk=account_id)
    session.speak("Welcome to %s" %
    server = Server.objects.all()[0]
    path = os.path.join(server.application_root,

Example Gateways

{| border="1" cellpadding="2"
| '''Field Name'''
| Field Value
| '''Gateway Name'''
| Free World Dialup
| '''Username'''
| <fwd number>
| '''Password'''
| <super secret password>
| '''Proxy'''
| '''Register'''
| yes (checked)
| '''Username'''
| <fwd number>
| '''Direction'''
| Both
| '''Extension'''
| <fwd number>
| '''From domain'''
| '''Max concurrent'''
| 10000000

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License