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

Inbound mode means you run your applications (in whatever languages) as clients and connect to the FreeSWITCH server to invoke commands and control FreeSWITCH.

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

Outbound mode means you make a daemon (with whatever language) and then have FS connect to it. You add a extension on the dialplan and put <action application="socket" data="ip:port sync full"/> and create a script that runs on that ip:port and do the answer, playback and everything else you need on the script.

In outbound mode, also known as the "socket application" (or socket client), 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 (in a default configuration this is located in /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml)

By default the module is enabled but restricted to localhost by the settings specified below.

The module settings can be changed in the event_socket.conf.xml file (in a default configuration this is located in /usr/local/freeswitch/conf/autoload_configs/event_socket.conf.xml):

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, written in Ruby, 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 (embedding various parameters in HTTP headers), so you can write your own http-speaking finite state machine and hook it to FreeSWITCH via Liverpie. Note also that Liverpie expects the response in YAML so you can save yourself the pain of providing XML if you are comfortable with Liverpie doing the translation.

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. Note that you need to provide a double empty line after the command so it processed.

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 or json 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.

then you may want to register for CHANNEL_ANSWER also, it is enough to give

event plain CHANNEL_ANSWER

and you will continue to receive DTMF along with CHANNEL_ANSWER, later one doesn't override the previous.

Special Case - 'myevents'

The 'myevents' subscription allows your inbound socket connection to behave like an outbound socket connect. It will "lock on" to the events for a particular uuid and will ignore all other events, closing the socket when the channel goes away or closing the channel when the socket disconnects and all applications have finished executing.

Usage:

myevents <uuid>

Once the socket connection has locked on to the events for this particular uuid it will NEVER see any events that are not related to the channel, even if subsequent event commands are sent. If you need to monitor a specific channel/uuid and you need watch for other events as well then it is best to use a filter.

You can also set the event format (plain, xml or json):

Usage:

myevents plain <uuid>
myevents json <uuid>
myevents xml <uuid>

The default format is plain.

divert_events

The divert_events switch is available to allow events that an embedded script would expect to get in the inputcallback to be diverted to the event socket.

Examples:

divert_events on
divert_events off

An inputcallback can be registered in an embedded script using setInputCallback(). Setting divert_events to "on" can be used for chat messages like gtalk channel, ASR events and others.

Read more

filter

Specify event types to listen for. Note, this is not a filter out but rather a "filter in," that is, when a filter is applied only the filtered values are received. Multiple filters on a socket connection are allowed.

Usage:

filter <EventHeader> <ValueToFilter>

Example:

The following example will subscribe to all events and then create two filters, one to listen for HEARTBEATS and one to listen for CHANNEL_EXECUTE events.

Now only HEARTBEAT and CHANNEL_EXECUTE events will be received. You can filter on any of the event headers. To filter for a specific channel you will need to use the uuid:

filter Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe

This method is an alternative to the myevents event type. If you need only the events for a specific channel then use myevents, otherwise use a combination of filters to narrow down the events you wish to receive on the socket.

filter delete

Specify the events which you want to revoke the filter. filter delete can be used when some filters are applied wrongly or when there is no use of the filter.

Usage:

filter delete <EventHeader> <ValueToFilter>

Example:

filter delete Event-Name HEARTBEAT

Now, you will no longer receive HEARTBEAT events. You can delete any filter that is applied by this way.

filter delete Unique-ID d29a070f-40ff-43d8-8b9d-d369b2389dfe

This is to delete the filter which is applied for the given unique-id. After this, you won't receive any events for this unique-id.

filter delete Unique-ID

This deletes all the filters which are applied based on the unique-id.

sendevent

Send an event into the event system (multi line input for headers)

sendevent <event-name>

The event generated by sendevent has the correct event type in the internal event structure,
so nodes which have subscribed to this event type will get the event, but unfortunately the "Event-Name" header field is always "COMMAND". In fact, the received event is simply a clone of the original COMMAND event for "sendevent" itself.

NOTE: This apparently is a bug that is being addressed. As a work-around, you can send sendevent without specifying an event type, and include a Event-Name header with the desired event name. For example:

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 behavior 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.

Since messaging format is similar to RFC2882. If you are using any libraries that following line wrapping recommendation of RFC 2822 make sure that you disable line wrapping as FreeSWITCH will ignore wrapped line.

hangup

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
it's good because then spandsp isn't living inside of FreeSWITCH
it can run on a box sitting next to it
scales better