mod_event_socket

About

mod_event_socket is a TCP-based interface to control FreeSWITCH, and it operates in two modes, inbound and outbound. (These terms are relative to FreeSWITCH).

By default, connections are only allowed from localhost, but this can be changed via configuration files (see Configuration section below for details).

Table of Contents (click to expand)

Subpages (click to expand)

Configuration

First enable the mod_event_socket module in <conf_dir>/autoload_configs/modules.conf.xml by removing the comment marks ( ).

Enabled by default

mod_event_socket is enabled by default for installations with vanilla configuration (i.e., when compiled from source or installed via package managers).

Find the location of <conf_dir>

To get the location of <conf_dir> , use eval $${conf_dir} in fs_cli .

The default settings, in the <conf_dir>/autoload_configs/event_socket.conf.xml configuration file, allow socket connections only from localhost (see below),

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <param name="nat-map" value="false"/>
    <!-- ::1 is the IPv6 version of 127.0.0.0/8 in IPv4 -->
    <param name="listen-ip" value="::1"/>
    <param name="listen-port" value="8021"/>
    <param name="password" value="ClueCon"/>
    <!--<param name="apply-inbound-acl" value="loopback.auto"/>-->
    <!--<param name="stop-on-bind-error" value="true"/>-->
  </settings>
</configuration>

but this behaviour can be changed using the listen-ip parameter. For example, to allow connections from any host on the network, use 0.0.0.0 instead of the default:

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <!-- Allow socket connections from any host -->
    <!-- :: is the IPv6 version of 0.0.0.0 in IPv4 -->
    <param name="listen-ip" value="::"/>
    <param name="listen-port" value="8021"/>
    <param name="password" value="ClueCon"/>
  </settings>
</configuration>

IPv6 support

You can listen on IPv6 addresses (with the listen-ip parameter) since revision 8c794ac.

For example, the above example using :: (IPv6 equivalent of 0.0.0.0) will enable listening on both IPv4 and IPv6 addresses on dual stack hosts.

ACL

Using ACLs is recommended for enhanced security if you allow ESL connections from another machine. One can either enable named ACLs (defined in <conf_dir>/autoload_configs/acl.conf.xml) or allow IP ranges directly in event_socket.conf.xml:

Syntax

<param name="apply-inbound-acl" value="<acl_list|cidr>"/>

Examples

<param name="apply-inbound-acl" value="10.20.0.0/16"/>
<param name="apply-inbound-acl" value="loopback.auto"/>

Multiple apply-inbound-acl params will not work.

As of 1.6 you must supply an ACL. In order to allow all IPs you can use any_v4.auto in event_socket.conf.xml.

Modes of operation

Inbound mode

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

    ********************************************
    *                     |                    *
    *  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: Python, Client B: 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.

If you would like to handle incoming calls using inbound mode, you should add the uuid_park command (see mod_commands) to your dialplan. Otherwise the dialplan might complete executing before your client can send commands to the event socket.

Outbound mode

Outbound mode means you make a daemon (with whatever language), and then have FreeSWITCH connect to it. You add an extension to the dialplan, and put <action application="socket" data="ip:port sync full"/> and create a script that runs on that ip:port and answer, playback and everything else you need on the script. Since revision git-8c794ac on 14/03/2012 you can connect to IPv6 addresses. When using IPv6 addresses the port parameter is required: <action application="socket" data="::1:8021"/> connects to ::1 on port 8021. Since this revision hostnames resolving to IPv6 addresses can be used.

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.

Command Documentation

The following section aims at documenting all commands that can be sent. This section is a work in progress.

api

Send a FreeSWITCH API command, blocking mode. That is, the FreeSWITCH instance won't accept any new commands until the api command finished execution.

Usage

api <command> <arg>

Examples

api originate sofia/mydomain.com/ext@yourvsp.com 1000   # connect sip:ext@yourvsp.com to extension 1000
api msleep 5000

bgapi

Send a FreeSWITCH 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.

Usage

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.

If you want to set your own custom Job-UUID over plain socket:

bgapi status
Job-UUID: d8c7f660-37a6-4e73-9170-1a731c442148

Reply:

Content-Type: command/reply
Reply-Text: +OK Job-UUID: d8c7f660-37a6-4e73-9170-1a731c442148
Job-UUID: d8c7f660-37a6-4e73-9170-1a731c442148

linger

Tells FreeSWITCH not to close the socket connection when a channel hangs up. Instead, it keeps the socket connection open until the last event related to the channel has been received by the socket client.

Usage

linger

nolinger

Disable socket lingering. See linger above.

Usage

nolinger

event

Enable or disable events by class or all (plain or xml or json output format)

Usage

event plain <list of events to log or all>
event xml <list of events to log or all>
event json <list of events to log or 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.

Examples

event plain ALL
event plain CHANNEL_CREATE CHANNEL_DESTROY CUSTOM conference::maintenance sofia::register sofia::expire
event xml ALL
event json CHANNEL_ANSWER

Subsequent calls to 'event' won't override the previous event sets. Supposing, you've first registered for DTMF

event plain DTMF

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 Cases

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.

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.

  events plain all

  Content-Type: command/reply
  Reply-Text: +OK event listener enabled plain


  filter Event-Name CHANNEL_EXECUTE

  Content-Type: command/reply
  Reply-Text: +OK filter added. [filter]=[Event-Name CHANNEL_EXECUTE]


  filter Event-Name HEARTBEAT

  Content-Type: command/reply
  Reply-Text: +OK filter added. [Event-Name]=[HEARTBEAT]

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.

To filter multiple unique IDs, you can just add another filter for events for each UUID. This can be useful for example if you want to receive start/stop-talking events for multiple users on a particular conference.

  filter plain all
  filter plain CUSTOM conference::maintenance
  filter Unique-ID $participantB
  filter Unique-ID $participantA
  filter Unique-ID $participantC

This will give you events for Participant A,B and C on any conference. To receive events for all users on a conference you can use something like:

filter Conference-Unique-ID $ConfUUID

You can filter on any of the parameters you get in a freeSWITCH event:

  filter plain all
  filter call-direction Inbound
  filter Event-Calling-File mod_conference.c
  filter Conference-Unique-ID $ConfUUID

You can use them individually or compound them depending on whatever end result you desire for the type of events you want to receive

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>

For MWI you make the FreeSWITCH 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)

Example of sendevent to switch phone MWI led (tested on yealink)

No Message:

MWI No Message

sendevent  message_waiting
MWI-Messages-Waiting: no
MWI-Message-Account: sip:user1@192.168.1.14

Some Message:

MWI With Message

sendevent  message_waiting
MWI-Messages-Waiting: yes
MWI-Message-Account: sip:user1@192.168.1.14
MWI-Voice-Message: 0/1 (0/0)

To have Snom phones reread their settings from the settings server you can use:

Snom NOTIFY

sendevent NOTIFY
profile: internal
event-string: check-sync;reboot=false
user: 1000
host: 192.168.10.4
content-type: application/simple-message-summary

Example of sendevent with a message body, the length of the body is specified by content-length:

sendevent NOTIFY
profile: internal
content-type: application/simple-message-summary
event-string: check-sync
user: 1005
host: 192.168.10.4
content-length: 2

OK

SIP Proxy Example

To send through a proxy, use the event headers: contact-uri, to-uri, and from-uri
In this example, the SIP proxy is 192.168.207.156:5060 and the UA can be reached at 1002@192.168.0.99:11710

sendevent NOTIFY
profile: internal
content-type: application/simple-message-summary
event-string: check-sync
user: 1002
host: 3.local
to-uri: 1002@3.local
from-uri: 1002@3.local
contact-uri: sip:1002@192.168.0.99:11710;fs_path=sip:192.168.207.156:5060

Another example with a notify:

NOTIFY Example

sendevent NOTIFY
profile: internal
content-type: application/simple-message-summary
event-string: check-sync
user: 1005
host: 99.157.44.194
content-length: 2

OK

Results in a packet like this:

NOTIFY Result

NOTIFY sip:1005@99.157.44.203 SIP/2.0
Via: SIP/2.0/UDP 99.157.44.194;rport;branch=z9hG4bKpH2DtBDcDtg0N
Max-Forwards: 70
From: <sip:1005@99.157.44.194>;tag=Dy3c6Q1y15v5S
To: <sip:1005@99.157.44.194>
Call-ID: 129d1446-0063-122c-15aa-001a923f6a0f
CSeq: 104766492 NOTIFY
Contact: <sip:mod_sofia@99.157.44.194:5060>
User-Agent: FreeSWITCH-mod_sofia/1.0.trunk-9578:9586
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, PRACK, MESSAGE, SUBSCRIBE, NOTIFY, REFER, UPDATE, REGISTER, INFO, PUBLISH
Supported: 100rel, timer, precondition, path, replaces
Event: check-sync
Allow-Events: talk, presence, dialog, call-info, sla, include-session-description, presence.winfo, message-summary
Subscription-State: terminated;timeout
Content-Type: application/simple-message-summary
Content-Length: 2

OK

Example for Sipura/Linksys/Cisco phone or ATA to resync config with a specified profile URL:

Cisco Resync

sendevent NOTIFY
profile: internal
event-string: resync;profile=http://10.20.30.40/profile.xml
user: 1000
host: 10.20.30.40
content-type: application/simple-message-summary
to-uri: sip:1000@10.20.30.40
from-uri: sip:1000@10.20.30.40

Results in a packet like this:

Cisco Resync result

NOTIFY sip:1000@10.20.30.41:5060 SIP/2.0
Via: SIP/2.0/UDP 10.20.30.40:5060;rport;branch=z9hG4bKyK4gHN28Hpyaa
Max-Forwards: 70
From: <sip:1000@10.20.30.40>;tag=FDXet6B470F6B
To: <sip:1000@10.20.30.40>
Call-ID: 19ff59fb-2cfc-1230-66b7-00199988ac0c
CSeq: 29295547 NOTIFY
Contact: <sip:mod_sofia@10.20.30.40:5060>
User-Agent: FreeSWITCH-mod_sofia/1.0.head-git-12f2bdf 2011-11-28 16-45-59 -0600
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, UPDATE, INFO, REGISTER, REFER, NOTIFY, PUBLISH, SUBSCRIBE
Supported: timer, precondition, path, replaces
Event: resync;profile=http://10.20.30.40/profile.xml
Allow-Events: talk, hold, presence, dialog, line-seize, call-info, sla, include-session-description, presence.winfo, message-summary, refer
Subscription-State: terminated;reason=timeout
Content-Type: application/simple-message-summary
Content-Length: 0

If 'Auth Resync-Reboot' is set to yes (default) in the phone than you have to specify the reverse-auth-user and reverse-auth-pass fields
If you only put 'event-string: resync' in the body then the unit will use its stored profile URI

Example usage for CSTA event:

CSTA Event

sendevent SWITCH_EVENT_PHONE_FEATURE
profile: internal
user: ex1004
host: 3.local
device: ex1004
Feature-Event: DoNotDisturbEvent
doNotDisturbOn: on

Example of send event with a MESSAGE and a message body, the length of the body is specified by content-length:

Send Message

sendevent SEND_MESSAGE
profile: internal
content-length: 2
content-type: text/plain
user: 1005
host: 99.157.44.194

OK

Results in a packet like this:

Send Message result

MESSAGE sip:1005@99.157.44.203 SIP/2.0
Via: SIP/2.0/UDP 99.157.44.194;rport;branch=z9hG4bK0apcKrtycp64p
Max-Forwards: 70
From: <sip:1005@99.157.44.194>;tag=4c0Dp49yUNmXH
To: <sip:1005@99.157.44.194>
Call-ID: 29916da5-0062-122c-15aa-001a923f6a0f
CSeq: 104766296 MESSAGE
Contact: <sip:mod_sofia@99.157.44.194:5060>
User-Agent: FreeSWITCH-mod_sofia/1.0.trunk-9578:9586
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, PRACK, MESSAGE, SUBSCRIBE, NOTIFY, REFER, UPDATE, REGISTER, INFO, PUBLISH
Supported: 100rel, timer, precondition, path, replaces
Content-Type: text/plain
Content-Length: 2

OK

To display a text message on a Snom 370 or Snom 820 the message must be of type "text/plain".

Authentication

Some phones require authentication for NOTIFY requests. FS can respond to a digest challenge if reverse authentication credentials are supplied for the user. See: XML User Directory

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

Something that was undocumented but is supported; SIP INFO messages can be sent to every IP you need.

sendevent SEND_INFO
profile: external
content-type: text/plain
to-uri: sip:1@2.3.4.5
from-uri: sip:1@1.2.3.4
content-length: 15

test

0. `sendmsg`

Usage

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 uuid (the unique id for each call/session).

originate a call directly to park by making an ext the ext part of the originate command &park()

All sendmsg commands must be followed by 2 returns.

Since messaging format is similar to RFC 2822, if you are using any libraries that follow the line wrapping recommendation of RFC 2822 then make sure that you disable line wrapping as FreeSWITCH will ignore wrapped lines. See "FreeSWITCH EventSocket header length" post for more.

Example

sendmsg <uuid>
call-command: execute
execute-app-name: playback
execute-app-arg: /tmp/test.wav

0.1. Commands

0.1.1. `execute`

execute is used to execute dialplan applications. Check the XML Dialplan and mod_dptools pages for available applications.

The format should be:

Execute format

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>

This alternate format can be used for app args that are truncated by the module's 2048 octet limit:

sendmsg <uuid>
call-command: execute
execute-app-name: <one of the applications>
loops: <number of times to invoke the command, default: 1>
content-type: text/plain
content-length: <content length>

<application data>

When an application is executed via sendmsg, CHANNEL_EXECUTE and CHANNEL_EXECUTE_COMPLETE events are going to be generated. If you would like to correlate these two events then add an Event-UUID header with your custom UUID. In the corresponding events, the UUID will be in the Application-UUID header. If you do not specify an Event-UUID, Freeswitch will automatically generate a UUID for the Application-UUID.

Example:

Event-UUID: 22075ce5-b67b-4f04-a6dd-1726ec14c8bf

0.1.2. `hangup`

Hang up the call.

Format

sendmsg <uuid>
call-command: hangup
hangup-cause: <one of the causes listed below>

Additional information

Hangup Causes

0.1.3. `unicast`

unicast is used to hook up spandsp for faxing over a socket.

Brian's note

That is a nice way for a script or app that uses the socket interface to get at the media. It's good because then spandsp isn't living inside of FreeSWITCH and it can run on a box sitting next to it. It scales better.

unicast example

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>
and optionally
flags: native - don't transcode audio to/from L16

0.1.4. `nomedia`

No description.

sendmsg <uuid>
call-command: nomedia
nomedia-uuid: <noinfo>

0.1.5. `xferext`

TODO Document this command.

From Stéphane Alnet's comment:

The description is missing `xferext`, which adds `application` to an extension then transfer the channel to that extension (whatever that means! ).

switch_ivr.c:503 lists the available commands, and that C file also contains the logic.

src/switch_ivr.c

	unsigned long CMD_EXECUTE = switch_hashfunc_default("execute", &hlen);
	unsigned long CMD_HANGUP = switch_hashfunc_default("hangup", &hlen);
	unsigned long CMD_NOMEDIA = switch_hashfunc_default("nomedia", &hlen);
	unsigned long CMD_UNICAST = switch_hashfunc_default("unicast", &hlen);
	unsigned long CMD_XFEREXT = switch_hashfunc_default("xferext", &hlen);

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>

Suppress the specified type of event. Useful when you want to allow 'event all' followed by 'nixevent <some_event>' to see all but 1 type of event.

noevents

noevents

Disable all events that were previously enabled with event.

Page tree

About

Configuration

ACL

Modes of operation

Inbound mode

Outbound mode

Command Documentation

api

bgapi

linger

nolinger

event

Special Cases

myevents

divert_events

Read more

filter

filter delete

sendevent

SIP Proxy Example

0. `sendmsg`

0.1. Commands

0.1.1. `execute`

0.1.2. `hangup`

0.1.3. `unicast`

0.1.4. `nomedia`

0.1.5. `xferext`

exit

auth

log

nolog

nixevent

noevents

See Also

Page tree

mod_event_socket

About

Configuration

ACL

Modes of operation

Inbound mode

Outbound mode

Command Documentation

api

bgapi

linger

nolinger

event

Special Cases

myevents

divert_events

Read more

filter

filter delete

sendevent

SIP Proxy Example

0. sendmsg

0.1. Commands

0.1.1. execute

0.1.2. hangup

0.1.3. unicast

0.1.4. nomedia

0.1.5. xferext

exit

auth

log

nolog

nixevent

noevents

See Also

0. `sendmsg`

0.1.1. `execute`

0.1.2. `hangup`

0.1.3. `unicast`

0.1.4. `nomedia`

0.1.5. `xferext`