Controlling VoIP features via API with Python

As we knows in the world have two famous Open Source VoIP projects. One of them “Asterisk” and other is “FreeSWITCH“. In this article I will describe how to use VoIP API features with Python, configuration spy module, configuration of IVR and control session flow with python script in the “FreeSWITCH” server.

Control FreeSWITCH with API remotely

In the python code worked server install needed libraries:

# python -m pip install esl
# python -m pip install FreeSWITCH-ESL-Python

Create script with name

Add the following lines to the “/etc/freeswitch/autoload_configs/acl.conf.xml” file in the FreeSWITCH server( is place from where “” code is connecting to the FreeSWITCH server):

<list name="" default="allow">
   <node type="allow" cidr=""/>

At the end restart FreeSWITCH server:

# systemctl restart freeswitch

If you want to see the channel variables just create “ ” script in the FreeSWITCH server and execute it(Don’t forget minimum one call must be present at script using time).

Result of this code will be as following:

root@fspush:~# ./
Variable name is: uuid
Result is: 3e88b243-50ad-4845-94ce-a6d6a647fec1

Variable name is: direction
Result is: inbound

Variable name is: presence_id
Result is: 1002@ip.address.fs.server

Variable name is: accountcode
Result is: 1002

Variable name is: call_uuid
Result is: 3e88b243-50ad-4845-94ce-a6d6a647fec1

Variable name is: hostname
Result is: fspush

Break selected UUID:

freeswitch@fspush> uuid_break 3e88b243-50ad-4845-94ce-a6d6a647fec1 all

Check UUID if exists:

freeswitch@fspush> uuid_exists 3e88b243-50ad-4845-94ce-a6d6a647fec1

Print all channel variables for selected UUID:

freeswitch@fspush> uuid_dump 3e88b243-50ad-4845-94ce-a6d6a647fec1


Configure FreeSWITCH IVR with python script

If you want configure your own IVR then firstly uncomment the following line in the “/etc/freeswitch/autoload_configs/modules.conf.xml” file:

<load module="mod_flite"/>

In the “/etc/freeswitch/dialplan/default” folder create new “welcome.xml” IVR configuration file for the “2920” extension. This configuraions calls “” python script file.

In the “/usr/share/freeswitch/scripts” folder create python file

Restart FreeSWITCH server:

# systemctl restart freeswitch

At the end just call from sip client to “2920” number and listen Text to Speech.

Control VoIP session flow with Python codes

Install Debian 8.5 and the install FreeSWITCH from official repository with the following commands:

# wget -O - | apt-key add -
# echo "deb jessie main" > /etc/apt/sources.list.d/freeswitch.list
# apt-get update && apt-get dist-upgrade -y && apt-get install -y freeswitch-meta-all

Install Python development and pip packages:

# apt-get install python-dev python-pip -y

After installation try to find file for API use (This file configured automatically from FreeSWITCH packages. This file will be used as FreeSWITCH library):

root@fspush:~# find / -name

Look at symbolic link:

# ll /usr/lib/pymodules/python2.7/
lrwxrwxrwx 1 root root 33 Mar 14 07:31 /usr/lib/pymodules/python2.7/ -> /usr/share/pyshared/

Uncomment the following line in the “/etc/freeswitch/autoload_configs/modules.conf.xml” file:

<load module="mod_python"/>

Note: If you want post data to web server then, in the “/etc/freeswitch/dialplan/default.xml” file add the following lines for the “Local_Extension“:

<action application="curl" data="http://IP.addr.of.server/ post id=${destination_number}" json inline="true"/>
<action application="set" data="respdata=${curl_response_data}"/>

In the “/usr/share/freeswitch/scripts” folder create python file

In the “/etc/freeswitch/dialplan/default.xml” file search “Local_Extension” and add the following line to this extension:

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

Give permission to write a file:

# chown -R freeswitch:freeswitch /usr/share/freeswitch/scripts/

Restart the service:

# systemctl restart freeswitch

In the “fs_cli” console check “mod_python” as following:

freeswitch@fspush> module_exists mod_python

Call from extension “1002” to “1009” and look at result in the “newfile.txt” file:

root@fspush:~# cat /usr/share/freeswitch/scripts/newfile.txt
Caller Number is: 1002
Called Number is: 1009

If you uncomment the following lines in the “” file then, each call will be answered with the “hold_music” variable:

#session.execute("playback", session.getVariable("hold_music"))

If you want forward calls for selected extension just add the following lines under “handler()” function(If extension “1002” will call to “1004” then, call will be forwarded to the “1006” and if “1003” call to “1002” it will play music file):

if session.getVariable("caller_id_name") == '1002' and session.getVariable("destination_number") == '1004':
    freeswitch.consoleLog('info', 'Caller Number: %s\n' % session.getVariable("caller_id_name"))
    with open('/usr/share/freeswitch/scripts/newfile.txt', 'w') as yaz:
        yaz.write('Caller number is: {0}, Called number is: {1}'.format(session.getVariable("caller_id_name"), session.getVariable("destination_number")))
    session.execute("execute_extension", "'{0}' XML default".format('1006'))
elif session.getVariable("caller_id_name") == '1003' and session.getVariable("destination_number") == '1002':
    freeswitch.consoleLog('info', 'Comparing does not success result!!!\n')

Hidden listening sip clients with SPY module

Add the following lines to the “/etc/freeswitch/dialplan/default.xml” file before “Local_Extension“:

<extension name="user_spy">
  <condition field="destination_number" expression="^\*0(\d{4})$">
    <action application="answer"/>
    <action application="userspy" data="$1@${domain_name}"/>

Uncomment the following line in the “/etc/freeswitch/autoload_configs/modules.conf.xml” file:

<load module="mod_spy"/>

At the end restart FreeSWITCH with the following command:

# systemctl restart freeswitch

Just call to “*01003” number to listen caller_ID1003“.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s