Mod event socket
From FreeSWITCH Wiki
Contents |
Introduction
mod_event_socket is a tcp based interface to control FreeSwitch. The default values are to bind to 127.0.0.1 port 8021 and the default password is ClueCon. See the Configuration section below for a note on when to use 0.0.0.0 instead of 127.0.0.1.
The module operates in two modes, inbound and outbound.
Inbound
********************************************
* | *
* FreeSWITCH™ | mod_event_socket *
* | 127.0.0.1:8021 *
* | *
********************************************
/\ /\
/ \
****************** ******************
* Client A * * Client B *
* 127.0.0.1:9988 * * 127.0.0.1:9999 *
****************** ******************
In inbound mode, your application (Client A, Client B: Python, Perl, etc) connects to the FreeSWITCH™ server on the given port and sends commands, as shown in the above diagram. The rest of this document is biased toward this inbound mode, though there is a lot of overlap with outbound mode. Using inbound socket connections you can check status, make outbound calls, etc.
Outbound
In outbound mode, also known as the "socket application", FreeSWITCH™ makes outbound connections to another process (similar to Asterisk's FAGI model). Using outbound connections you can have FreeSWITCH™ call your own application(s) when particular events occur. See Event socket outbound for more details regarding things specific to outbound mode.
Configuration
First enable the mod_event_socket module in modules.conf.xml
The module settings can be changed in the event_socket.conf.xml file:
<configuration name="event_socket.conf" description="Socket Client">
<settings>
<param name="listen-ip" value="127.0.0.1"/>
<param name="listen-port" value="8021"/>
<param name="password" value="ClueCon"/>
</settings>
</configuration>
The default settings allow socket connections only from the local host. To allow connections from any host on the network, use 0.0.0.0 instead of the default 127.0.0.1:
<configuration name="event_socket.conf" description="Socket Client">
<settings>
<!-- Allow socket connections from any host -->
<param name="listen-ip" value="0.0.0.0"/>
<param name="listen-port" value="8021"/>
<param name="password" value="ClueCon"/>
</settings>
</configuration>
ACL
Access lists can be created in acl.conf.xml and enabled in event_socket.conf.xml or allow ip ranges directly in event_socket.conf.xml
<param name="apply-inbound-acl" value="<acl_list|cidr>"/>
Example Clients
The idea is that you would write your own client... but here are some examples.
Liverpie
Liverpie (language independent IVR proxy) is a free little piece of software that talks to FreeSWITCH on one side, and to any web application on the other, regardless of language, platform etc. It translates FreeSWITCH mod_socket dialogue into HTTP talk, so you can write your own finite state machine (which is what any IVR is) and hook it to FreeSWITCH via Liverpie.
Find Liverpie here: www.liverpie.com
Comment stony999: I tested Liverpie in Detail. The concept is perfect for writing IVRs and I love this approach. Hower I had a lot of problems with the server component which acts against Freeswitch. It turned out that Liverpie doesn't parse all the packages correctly as it assumes, that a packet only delivers one command at a time terminated by \n\n. But some command are delivered combined in one package and sometimes FS even delivers only parts of a full request in one packet (terminated by \n\n), so this also fails. Thus I couldn' get it to work correctly and had to rewrite it extensively.
Comment by alxx: Thanks for testing, Peter. I've just released Liverpie 0.3 which hopefully addresses some of your issues. I couldn't replicate your issues about packages that Liverpie ignores. Yes, FS sometimes delivers packets in chunks, each terminated by \n\n, but Liverpie merges those together. Shouldn't we move this talk into the 'discussion' page?
telnet client
telnet to port 8021 and enter "auth ClueCon" as password to authenticate. From here you can send any of the commands listed in this document.
perl command client
there is a perl client in scripts/socket called fs.pl
with the module up and loaded:
cd scripts/socket perl fs.pl <optional log level>
you can enter a few api commands like "show" or "status"
python client library
In the script/socket/freepy directory, there is a python client library based on the Twisted asynchronous socket library. An example is included.
php client
Website based PHP example PHP Event Socket
Command documentation
The following section aims at documenting all commands that can be sent. This section is work in progress.
api
Send an api command (blocking mode)
api <command> <arg>
Api commands are documented in the mod_commands section
Examples:
api originate sofia/mydomain.com/ext@yourvsp.com 1000 # connect sip:ext@yourvsp.com to extension 1000 api sleep 5000
bgapi
Send an api command (non-blocking mode) this will let you execute a job in the background and the result will be sent as an event with an indicated uuid to match the reply to the command)
bgapi <command> <arg>
The same API commands available as with the api command, however the server returns immediately and is available for processing more commands.
Example return value:
Content-Type: command/reply Reply-Text: +OK Job-UUID: c7709e9c-1517-11dc-842a-d3a3942d3d63
When the command is done executing, freeswitch fires an event with the result and you can compare that to the Job-UUID to see what the result was. In order to receive this event, you will need to subscribe to BACKGROUND_JOB events.
event
Enable or disable events by class or all (plain or xml output format)
event plain <list of events to log or all for all>
The event command are used to subscribe on events from freeswitch. You may specify any number events on the same line, they should be separated with space.
The events are listed in the Event list page.
Subsequent calls to 'event' will override and disable previous event sets.
Examples;
event plain ALL event plain CUSTOM conference::maintenence event plain CHANNEL_CREATE CHANNEL_DESTROY CUSTOM conference::maintenence sofia::register sofia::expire
Read more
sendevent
Send an event into the event system (multi line input for headers)
sendevent <event-name>
For MWI you make the FS event SWITCH_EVENT_MESSAGE_WAITING with headers
MWI-Messages-Waiting (yes/no) MWI-Message-Account <any sip url you want> MWI-Voice-Message x/y (a/b) read/unread (urgent read/urgent unread)
To have Snom phones reread their settings from the settings server you can use:
sendevent NOTIFY profile: internal event-string: check-sync;reboot=false user: 1000 host: 192.168.10.4 content-type: application/simple-message-summary
I've not found any documentation of any additional event headers, hopefully someone else with add that information. The events themselves can be found here: Event list
sendevent CHANNEL_HANGUP
sendmsg
sendmsg <uuid>
Send a message to the call of given uuid (call-command execute or hangup), see examples below
Send message are used to send messages that controls the behaviour of FreeSwitch. You need to provide a uid (the unique id for each call/session).
In order to control calls using send message, the calls should be sent to the mod_park which just leaves the channel sitting in limbo, allowing you to execute applications on the channel as described above in the SendMsg example.
originate a call directly to park by making an ext the ext part of the originate command &park()
IMPORTANT! All SendMsg commands must be followed by 2 returns.
Example:
SendMsg <uuid> call-command: execute execute-app-name: playback execute-app-arg: /tmp/test.wav
call-command
The first command is Call-Command, it can do one of the following subcommands:
execute
Execute are used to execute applications, check the Dialplan XML section for more information about all commands.
The format should be:
SendMsg <uuid> call-command: execute execute-app-name: <one of the applications> execute-app-arg: <application data> loops: <number of times to invoke the command, default: 1>
hangup
Not so hard to guess what it does, right? =)
Format:
SendMsg <uuid> call-command: hangup hangup-cause: <one of the causes listed below>
Additional information
unicast
Unicast is used to hook up spandsp for in and outbound faxing over a socket.
Additional information from brian:
that is a nice way someone writing a script/app that uses the socket interface can get at the media its good because then spandsp isn't living inside of FreeSWITCH it can run on a box sitting next to it scales better
SendMsg <uuid> call-command: unicast local_ip: <default is 127.0.0.1> local_port: <default is 8025> remote_ip: <default is 127.0.0.1> remote_port: <default is 8026> transport: <either "tcp" or "udp", without the quotes>
nomedia
No description
SendMsg <uuid> call-command: nomedia nomedia-uuid: <noinfo>
exit
exit
close the socket connection
auth
auth <password>
log
log <level>
Enable log output. Levels same as the console.conf values
nolog
nolog
Disable log output previously enabled by the log command
nixevent
nixevent <event types | ALL | CUSTOM custom event sub-class>
command to allow 'events all' followed by 'nixevent <some_event>' to do all but 1 type scenerio
noevents
noevents
disable all events that were previously enabled w/ event
