Difference between revisions of "Mod event socket"

From FreeSWITCH Wiki
Jump to: navigation, search
m
m (Removed extra '=' signs on headers to help differentiate doc structure. Extra '=' signs make it harder to determine that call-command and the like are children of sendmsg.)
Line 1: Line 1:
==Introduction==
+
=Introduction=
  
 
mod_event_socket is a TCP based interface to control FreeSWITCH.
 
mod_event_socket is a TCP based interface to control FreeSWITCH.
Line 6: Line 6:
 
The module operates in two modes, inbound and outbound.
 
The module operates in two modes, inbound and outbound.
  
===Inbound===
+
==Inbound==
  
 
Inbound mode means you run your applications (in whatever languages) as clients and connect to the FS server to invoke commands and control FS.
 
Inbound mode means you run your applications (in whatever languages) as clients and connect to the FS server to invoke commands and control FS.
Line 27: Line 27:
 
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.
 
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==
  
 
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.
 
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.
Line 33: Line 33:
 
In outbound mode, also known as the "socket application" (or socket client), FreeSWITCH&trade; makes outbound connections to another process (similar to Asterisk's FAGI model). Using outbound connections you can have FreeSWITCH&trade; call your own application(s) when particular events occur. See [[Event Socket Outbound]] for more details regarding things specific to outbound mode.
 
In outbound mode, also known as the "socket application" (or socket client), FreeSWITCH&trade; makes outbound connections to another process (similar to Asterisk's FAGI model). Using outbound connections you can have FreeSWITCH&trade; call your own application(s) when particular events occur. See [[Event Socket Outbound]] for more details regarding things specific to outbound mode.
  
==Configuration==
+
=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)
 
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)
Line 66: Line 66:
 
</pre>
 
</pre>
  
=== ACL ===
+
== 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]]
 
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]]
  
Line 77: Line 77:
 
Note that multiple apply-inbound-acl params will not work.
 
Note that multiple apply-inbound-acl params will not work.
  
==Example Clients==
+
=Example Clients=
  
 
The idea is that you would write your own client... but here are some examples.
 
The idea is that you would write your own client... but here are some examples.
  
===Liverpie===
+
==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.
 
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.
 
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.
Line 93: Line 93:
 
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?
 
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 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.
 
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 event socket client|Perl Command Client]]===
+
==[[perl event socket client|Perl Command Client]]==
 
There is a Perl client in scripts/socket called fs.pl.
 
There is a Perl client in scripts/socket called fs.pl.
  
Line 106: Line 106:
 
You can enter a few api commands like "show" or "status".
 
You can enter a few api commands like "show" or "status".
  
=== Ruby Libraries ===
+
== Ruby Libraries ==
  
 
* [http://code.rubyists.com/projects/fs FreeSWITCHeR]
 
* [http://code.rubyists.com/projects/fs FreeSWITCHeR]
 
* [http://github.com/ichverstehe/librevox Librevox]
 
* [http://github.com/ichverstehe/librevox Librevox]
  
=== Python Client Library ===
+
== Python Client Library ==
  
 
In the scripts/python/freepy directory, there is a python client library based on the [http://www.twistedmatrix.com Twisted] asynchronous socket library.  An example is included.
 
In the scripts/python/freepy directory, there is a python client library based on the [http://www.twistedmatrix.com Twisted] asynchronous socket library.  An example is included.
Line 117: Line 117:
 
There's also an alternative [http://github.com/fiorix/eventsocket twisted protocol class for FreeSWITCH's event socket]. It currently supports inbound and outbound methods, and examples are included.
 
There's also an alternative [http://github.com/fiorix/eventsocket twisted protocol class for FreeSWITCH's event socket]. It currently supports inbound and outbound methods, and examples are included.
  
=== PHP Client ===
+
== PHP Client ==
 
Website based PHP example [[PHP Event Socket]]
 
Website based PHP example [[PHP Event Socket]]
  
=== Java Client Libraries ===
+
== Java Client Libraries ==
  
 
[[Java_ESL]] describes several options for using Java to communicate with the ESL.
 
[[Java_ESL]] describes several options for using Java to communicate with the ESL.
  
==Command documentation==
+
=Command documentation=
  
 
The following section aims at documenting all commands that can be sent.
 
The following section aims at documenting all commands that can be sent.
 
This section is work in progress.
 
This section is work in progress.
  
===api===
+
==api==
  
 
Send an api command (blocking mode)
 
Send an api command (blocking mode)
Line 141: Line 141:
 
  api sleep 5000
 
  api sleep 5000
  
===bgapi===
+
==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)
 
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)
Line 155: Line 155:
 
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 [[Event_list#BACKGROUND_JOB|BACKGROUND_JOB]] events.
 
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 [[Event_list#BACKGROUND_JOB|BACKGROUND_JOB]] events.
  
===event===
+
==event==
  
 
Enable or disable events by class or all (plain or xml or json output format)
 
Enable or disable events by class or all (plain or xml or json output format)
Line 179: Line 179:
 
and you will continue to receive DTMF along with CHANNEL_ANSWER, later one doesn't override the previous.
 
and you will continue to receive DTMF along with CHANNEL_ANSWER, later one doesn't override the previous.
  
====Special Case - 'myevents'====
+
===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.
 
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.
  
Line 187: Line 187:
 
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.
 
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.
  
====divert_events====
+
===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.  
 
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.  
Line 197: Line 197:
 
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.
 
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====
+
===Read more===
 
* [[Event List]]
 
* [[Event List]]
  
===filter===
+
==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.
 
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.
  
Line 233: Line 233:
 
This method is an alternative to the [[Mod_event_socket#Special_Case_-_.27myevents.27|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.
 
This method is an alternative to the [[Mod_event_socket#Special_Case_-_.27myevents.27|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===
+
==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.
 
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.
  
Line 253: Line 253:
 
This deletes all the filters which are applied based on the unique-id.
 
This deletes all the filters which are applied based on the unique-id.
  
===sendevent===
+
==sendevent==
  
 
Send an event into the event system (multi line input for headers)
 
Send an event into the event system (multi line input for headers)
Line 371: Line 371:
 
</pre>
 
</pre>
  
===sendmsg===
+
==sendmsg==
  
 
  sendmsg <uuid>
 
  sendmsg <uuid>
Line 393: Line 393:
 
  execute-app-arg: /tmp/test.wav
 
  execute-app-arg: /tmp/test.wav
  
====call-command====
+
===call-command===
  
 
The first command is Call-Command, it can do one of the following subcommands:
 
The first command is Call-Command, it can do one of the following subcommands:
  
=====execute=====
+
====execute====
  
 
Execute are used to execute applications, check the Dialplan XML section for more information about all commands.
 
Execute are used to execute applications, check the Dialplan XML section for more information about all commands.
Line 425: Line 425:
 
</pre>
 
</pre>
  
=====hangup=====
+
====hangup====
  
 
Hangup the call.
 
Hangup the call.
Line 440: Line 440:
 
* [[Hangup Causes]]
 
* [[Hangup Causes]]
  
=====unicast=====
+
====unicast====
  
 
Unicast is used to hook up spandsp for in and outbound faxing over a socket.
 
Unicast is used to hook up spandsp for in and outbound faxing over a socket.
Line 464: Line 464:
 
</pre>
 
</pre>
  
=====nomedia=====
+
====nomedia====
  
 
No description.
 
No description.
Line 474: Line 474:
 
</pre>
 
</pre>
  
===exit===
+
==exit==
  
 
  exit
 
  exit
Line 480: Line 480:
 
Close the socket connection.
 
Close the socket connection.
  
===auth===
+
==auth==
  
 
  auth <password>
 
  auth <password>
  
===log===
+
==log==
  
 
  log <level>
 
  log <level>
Line 490: Line 490:
 
Enable log output. Levels same as the console.conf values
 
Enable log output. Levels same as the console.conf values
  
===nolog===
+
==nolog==
  
 
  nolog
 
  nolog
Line 496: Line 496:
 
Disable log output previously enabled by the log command
 
Disable log output previously enabled by the log command
  
===nixevent===
+
==nixevent==
  
 
  nixevent <event types | ALL  | CUSTOM custom event sub-class>
 
  nixevent <event types | ALL  | CUSTOM custom event sub-class>
Line 502: Line 502:
 
Command to allow 'events all' followed by 'nixevent <some_event>' to do all but 1 type scenario.
 
Command to allow 'events all' followed by 'nixevent <some_event>' to do all but 1 type scenario.
  
===noevents===
+
==noevents==
  
 
  noevents
 
  noevents
Line 508: Line 508:
 
Disable all events that were previously enabled with event.
 
Disable all events that were previously enabled with event.
  
==Sample Event Socket Applications==
+
=Sample Event Socket Applications=
 
* [[Email2callback]] - Email to callback application with Python and freepy.
 
* [[Email2callback]] - Email to callback application with Python and freepy.
  
==See Also==
+
=See Also=
 
* [[Event_Socket_Library|Event Socket Library]]
 
* [[Event_Socket_Library|Event Socket Library]]
 
* [[Event_Socket_Outbound|Event Socket Outbound]]
 
* [[Event_Socket_Outbound|Event Socket Outbound]]

Revision as of 12:16, 23 October 2010

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

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

    ********************************************
    *                     |                    *
    *  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

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

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

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

Note that multiple apply-inbound-acl params will not work.

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.

Find Liverpie here: www.liverpie.com

As at 5Jan2010 - Liverpie is currently at version 0.5 and the comments below may be so out of date they should be removed. Could either party make a decision to clear them away or report more up to date issues?

Comment stony999: I tested Liverpie in Detail. The concept is perfect for writing IVRs and I love this approach. However 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't 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".

Ruby Libraries

Python Client Library

In the scripts/python/freepy directory, there is a python client library based on the Twisted asynchronous socket library. An example is included.

There's also an alternative twisted protocol class for FreeSWITCH's event socket. It currently supports inbound and outbound methods, and examples are included.

PHP Client

Website based PHP example PHP Event Socket

Java Client Libraries

Java_ESL describes several options for using Java to communicate with the ESL.

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

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

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.

  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.

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>  
Informational Tip

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:

 sendevent SOME_NAME
 Event-Name: CUSTOM
 Event-Subclass: albs::Section-Alarm
 Section: 33
 Alarm-Type: PIR
 State: ACTIVE

 

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

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

Another example with a notify:

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 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 of send event with a MESSAGE and a message body, the length of the body is specified by content-length:

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:

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


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.

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>


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>

hangup

Hangup the call.

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

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

noevents

noevents

Disable all events that were previously enabled with event.

Sample Event Socket Applications

  • Email2callback - Email to callback application with Python and freepy.

See Also