Call Us Today! 877.742.2583




Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleTable of Contents (click to expand)

Table of Contents
indent1em
excludeAbout
stylenone
printablefalse


Expand
titleSubpages (click to expand)

...

0. 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). 

...

titleTable of Contents (click to expand)
Panel
borderColorlightgray
bgColor#f7f7f7
borderWidth1
borderStyledotted

Table of Contents
maxLevel3
indent1em
excludeAbout
stylenone
printablefalse



Expand
titleSubpages (click to expand)

Configuration

1. Configuration

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

...

Info
titleIPv6 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.

1.1 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:

...

Warning

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.

2. Modes of operation

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

...

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.

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

3. Command Documentation

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

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

...

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

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

...

Code Block
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:

...

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

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

Code Block
titleUsage
linger

3.4 nolinger

Disable socket lingering. See linger above.

Code Block
titleUsage
nolinger

3.5 event

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

...

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

3.5.1 Special Cases

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

...

The default format is plain.

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

...

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.

...

3.5.1.3Read more

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

...

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

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

...

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

3.8 sendevent

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


Code Block
sendevent <event-name>
<headers>

<body>


Note

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


Info
titleUncategorized content

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.

Code Block
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



3.8.1 Examples

3.8.1.1 Switch phone MWI led (tested on yealink)

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:

Code Block
titleMWI No Message
sendevent  message_waiting
MWI-Messages-Waiting: no
MWI-Message-Account: sip:user1@192.168.1.14

...

Code Block
titleMWI 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)

...

3.8.1.2 Make Snom phones reread their settings from the settings server

...

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

...

3.8.1.3 sendevent examples with a message body

...

The length of the body is specified by content-length:the Content-Length header.

Code Block
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

or

Code Block
titleSend 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:

Code Block
titleSend 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
3.8.1.4 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

...

Code Block
titleNOTIFY 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

...

3.8.1.5 Sipura/Linksys/Cisco phone or ATA to resync config with a specified profile URL

...

Code Block
titleCisco 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 

...

  • 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
3.8.1.6 Example usage for CSTA event:
Code Block
titleCSTA 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:

Code Block
titleSend 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:

Code Block
titleSend 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

...

3.8.1.7 Display a text message on a Snom 370 or Snom 820

...

The message must be of type "text/plain".

Info
titleAuthentication

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

...

sendevent CHANNEL_HANGUP

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

Code Block
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

3.9 sendmsg

Code Block
titleUsage
sendmsg <uuid>
<headers>

<body>

Send a message to the call of given uuid UUID (channel?) (call-command execute or hangup), see examples below.

...

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

...

3.9.1

...

Commands

...

3.

...

9.1.execute

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

...

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

...

3.9.1.

...

hangup

Hang up the call.

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

Additional information

...

3.9.1.

...

unicast

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

...

Code Block
titleunicast 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

...

3.9.1.

...

nomedia

No description.

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

...

3.9.1.5

...

xferext
Note

Status
colourYellow
titleTODO
 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! (big grin) ).

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

Code Block
languagecpp
firstline503
titlesrc/switch_ivr.c
linenumberstrue
	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);


3.10 exit

Code Block
exit

Close the socket connection.

3.11 auth

Code Block
auth <password>

3.12 log

Code Block
log <level>

Enable log output. Levels same as the console.conf values

3.13 nolog

Code Block
nolog

Disable log output previously enabled by the log command

3.14 nixevent

Code Block
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.

3.15 noevents

Code Block
noevents

Disable all events that were previously enabled with event.

...