Mod commands

From FreeSWITCH Wiki
Revision as of 16:30, 21 May 2014 by Boteman (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



These are the commanded provided by mod_commands and is up to date as of r14778 (Sept 09). These commands can be issued via any of the following interfaces (not an exhaustive list):


See below.

API/Event Interfaces

Scripting Interfaces

From the Dialplan

An API can be called from the dialplan. Example:

 <extension name="Make API call from Dialplan">
   <condition field="destination_number" expression="^(999)$">
     <!-- next line calls hupall, so be careful! -->
     <action application="set" data="api_result=${hupall(normal_clearing)}"/>

Other examples:

 <action application="set" data="api_result=${status()}"/>
 <action application="set" data="api_result=${version()}"/>
 <action application="set" data="api_result=${strftime()}"/>
 <action application="set" data="api_result=${expr(1+1)}"/>

API commands with multiple arguments usually have the arguments separated by a space:

 <action application="set" data="api_result=${sched_api(+5 none avmd ${uuid} start)}"/>

The set of available commands is dependent on the modules that are loaded; the authoritative set of commands can be found from the set of commands registered by each module.

To see a list of available API commands simply type help or show api at the CLI.

NOTE: If you are calling an API from the dialplan make absolutely certain that there isn't already a dialplan application (see mod_dptools) that gives you the functionality you are looking for.

Core Commands

Implemented in

NOTE: Results of some status and listing commands are presented in comma delimited lists by default. Data returned from some modules may also contain commas, making it difficult to automate result processing. They may be able to be retrieved in an XML format by appending the string "as xml" to the end of the command string, or as json using "as json", or change the delimiter from comma to something else using "as delim |".


Compare an ip to an ACL list.

Usage: acl <ip> <list_name>


Alias: a means to save some keystrokes on commonly used commands.

Usage: alias add <alias> <command> | del [<alias>|*]


 freeswitch> alias add reloadall reloadacl reloadxml
 freeswitch> alias add unreg sofia profile internal flush_inbound_reg

You can add aliases that persist across restarts using the stickyadd argument:

 freeswitch> alias stickyadd reloadall reloadacl reloadxml

Note: Only really works from the console, not fs_cli.


Execute an API command in a thread.

Usage: bgapi <command>[ <arg>]



Usage: complete add <word>|del [<word>|*]


Eval a conditional.

Usage: cond <expr> ? <true val> : <false val>

Conditions supported by expr are:

== Equality
< Less than
> Greater than


Return true if first val is greater than the second

cond 5 > 3 ? true : false

Example in dialplan:

  <action application="set" data="voicemail_authorized=${cond(${sip_authorized} == true ? true : false)}"/>

Slightly more complex example:

  <action application="set" data="voicemail_authorized=${cond(${sip_acl_authed_by} == domains ? false : ${cond(${sip_authorized} == true ? true : false)})}"/>


Check if a domain exists.

Usage: domain_exists <domain>


Eval (noop). Evaluates a string, expands variables.

Usage: eval [uuid:<uuid> ]<expression>


eval ${domain}
eval Hello, World!
Hello, World!
eval uuid:e72aff5c-6838-49a8-98fb-84c90ad840d9 ${channel-state}


Execute an API with variable expansion.

Usage: [uuid:<uuid> ]<cmd> <args>


 expand originate sofia/internal/1001%${domain} 9999   

In this example the value of ${domain} is expanded. If the domain were, for example, "" then this command would be executed:

 originate sofia/internal/1001% 9999


Send FreeSWITCH control messages.

USAGE: fsctl [send_sighup |
              hupall |
              pause [inbound|outbound] |
              resume [inbound|outbound] |
              shutdown [cancel|elegant|asap|restart] |
              last_sps |
              sps [num] |
              sync_clock |
              sync_clock_when_idle |
              reclaim_mem |
              max_sessions |
              min_dtmf_duration [num] |
              max_dtmf_duration [num] |
              default_dtmf_duration [num] |
              loglevel [level] |
              verbose_events [on|off]


Can be used to disconnect existing calls to a destination. The parameters are: clearing_type dialed_ext <extension number>

For example to kill an active call with the destination being extension 1000:
fsctl hupall normal_clearing dialed_ext 1000


FreeSWITCH will not trust the system time. It gets one sample of system time when it first starts and uses the monotonic clock from there. You can sync it back to real time with "fsctl sync_clock"

Note: 'fsctl sync_clock' immediately takes effect - which can affect the times on your CDRs. You can end up undrebilling/overbilling, or even calls hungup before they originated. e.g. if FS clock is off by 1 month, then your CDRs are going to show calls that lasted for 1 month!

'fsctl sync_clock_when_idle' is much safer, which does the same sync but doesn't take effect until there are 0 channels in use. That way it doesn't affect any CDRs.


You can sync the clock but have it not do it till there are 0 calls (r:2094f2d3)


This changes the sessions-per-second limit as initially set in switch.conf


Query the actual sessions-per-second.


inbound or outbound may optionally be specified to pause just inbound or outbound session creation, both paused if nothing specified. resume has similar behavior.



fsctl min_dtmf_duration 800

This example sets the min_dtmf_duration switch parameter to 100ms. The number is in clock ticks where clockticks / 8 = ms. The min_dtmf_duration specifies the minimum DTMF duration to use on outgoing events. Events shorter than this will be increased in duration to match min_dtmf_duration. You cannot configure a DTMF duration on a profile that is less than this setting. You may increase this value, but cannot set it lower than 400 (the default). This value cannot exceed max_dtmf_duration. This setting can be changed in switch.conf.xml.

It is worth noting that many devices squelch in-band DTMF when sending RFC 2833. Devices that squelch in-band DTMF have a certain reaction time and clamping time which can sometimes reach as high as 40ms, though most can do it in less than 20ms. As the shortness of your DTMF event duration approaches this clamping threshold, the risk of your DTMF being ignored as a squelched event increases. If your call is always IP-IP the entire route, this is likely not a concern. However, when your call is sent to the PSTN, the RFC 2833 must be encoded in the audio stream. This means that other devices down the line (possibly a PBX or IVR you are calling into) might start considering your DTMF event a squelched tone and ignore it entirely. For this reason, it is recommended that you do not send DTMF events shorter than 80ms.

Checking the current value:

fsctl min_dtmf_duration 0

The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.



fsctl max_dtmf_duration 80000

This example sets the max_dtmf_duration switch parameter to 10,000ms (10 seconds). The number is in clock ticks (CT) where CT / 8 = ms. The max_dtmf_duration caps the playout of a DTMF event at the specified duration. Events exceeding this duration will be truncated to this duration. You cannot configure a duration on a profile that exceeds this setting. This setting can be lowered, but cannot exceed 192000 (the default). This setting cannot be set lower than min_dtmf_duration. This setting can be changed in switch.conf.xml.

Checking the current value:

fsctl max_dtmf_duration 0

The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.



fsctl default_dtmf_duration 2000

This example sets the default_dtmf_duration switch parameter to 250ms. The number is in clock ticks (CT) where CT / 8 = ms. The default_dtmf_duration specifies the DTMF duration to use on originated DTMF events or on events that are received without a duration specified. This value can be increased or lowered. This value is lower-bounded by min_dtmf_duration and upper-bounded by max_dtmf_duration. This setting can be changed in switch.conf.xml.

Checking the current value:

fsctl default_dtmf_duration 0

The code recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.


Enables verbose events. Verbose events have every channel variable in every event for a particular channel. Non-verbose events have only the pre-selected channel variables in the event headers.


Gets the value of a global variable. If the parameter is not provided then it gets all the global variables.

Usage: global_getvar <varname>


Sets the value of a global variable.

Usage: global_setvar <varname>=<value>


global_setvar foo=bar


Returns the bridge string defined in a call group.

 Usage: group_call group@domain[+F][+A][+E]

+F will return the group members in a serial fashion (separated by |), +A will return them in a parallel fashion (separated by ,) and +E will return them in a enterprise fashion (separated by :_:). See Groups in the XML User Directory for more information.

Please note: If you need to have outgoing user variables set in outgoing channel, make sure you don't have dial-string and group-dial-string in your domain or dialed group variables list, instead set dial-string or group-dial-string in default group of the user. This way group_call will return user/101 and user/ would set all your user variables to outgoing channel ...


Show help for all the API commands.

Usage: help


Performs a host lookup on a domain name.

Usage: host_lookup <hostname>


Disconnect existing channels.

Usage: hupall <cause> [<variable> <value>]

All channels that have set to <value> will be disconnected with <cause>


originate {foo=bar}sofia/internal/,sofia/internal/ &park

hupall normal_clearing foo bar


Determine if a user is in a group.

Usage: in_group <user>[@<domain>] <group_name>


See if an IP is a LAN address.

Usage: is_lan_addr <ip>


Load external module

Usage: load <mod_name>


Return MD5 hash for the given input data

Usage: md5 


Check if module exists.

Usage: module_exists <module>


Sleep for x number of milliseconds

Usage: msleep <number of milliseconds to sleep>


Usage: nat_map [status|reinit|republish] | [add|del] <port> [tcp|udp] [sticky] | [mapping] <enable|disable>
  • status - Gives the NAT type, the external IP, and the currently mapped ports.
  • reinit - Completely re-initializes the NAT engine. Use this if you have changed swapped out your router or have changed your router from NAT mode to UPnP mode.
  • republish - Causes FreeSWITCH to republish the NAT maps. This should not be necessary in normal operation.
  • mapping - Controls if port mapping requests will be sent to the NAT (the command line option of -nonatmap can set it to disable on startup). This gives the ability of still using NAT for getting public IP but without opening the ports in the NAT.

Note: sticky makes the mapping stay across FreeSWITCH restarts. It gives you a permanent mapping.

Warning: If you have multiple interfaces with sip profiles using the same port, nat_map *will* get confused when it tries to map the same ports for multiple profiles. Don't do that!


Evaluate a regex (regular expression). This command behaves differently depending upon whether or not a substitution string is supplied:

  • If a subst is not supplied, regex returns either true or false
  • If a subst is supplied, regex returns the subst value on a true condition, or the source string on a false condition (this is an update as of revision 14727, previously the regex would return "false" on a failed match.)

The regex delimiter defaults to the | (pipe) character. The delimiter may be changed to ~ (tilde) or / (forward slash) by prefixing the regex with m: (new behavior as of 14727).

Usage: regex <data>|<pattern>[|<subst string>]
       regex m:/<data>/<pattern>[/<subst string>]
       regex m:~<data>~<pattern>[~<subst string>]


regex test1234|\d                  <== Returns "true"
regex m:/test1234/\d               <== Returns "true"
regex m:~test1234~\d               <== Returns "true"
regex test|\d                      <== Returns "false"
regex test1234|(\d+)|$1            <== Returns "1234"
regex sip:foo@bar.baz|^sip:(.*)|$1 <== Returns "foo@bar.baz"
regex testingonetwo|(\d+)|$1       <== Returns "testingonetwo" (no match)
regex m:~30~/^(10|20|40)$/~$1      <== Returns "30" (no match)
regex m:~30~/^(10|20|40)$/~$1~n    <== Returns "" (no match)
regex m:~30~/^(10|20|40)$/~$1~b    <== Returns "false" (no match)

Logic in revision 14727 if the source string matches the result then the condition was false however there was a match and it is 1001.

regex 1001|/(^\d{4}$)/|$1


Reload a module.

Usage: reload [-f] <mod_name>


Reload ACL.

Usage: reloadacl [reloadxml]


Reload conf/freeswitch.xml settings

Usage: reloadxml


Display various reports

Usage: show <item> where <item> is:
 calls [count]
 channels [count|like <match string>]

XML formatted: show foo as xml

Change delimiter: show foo as delim |
  • codec - list codecs
  • endpoint - list endpoints
  • application - list applications
  • api - list api's
  • dialplan - list dialplan modules
  • file - list supported file formats
  • timer - list timer modules
  • calls - list current calls [count]
  • channels - list current channels [count|like <match string>] see Channels vs Calls
  • bridged_calls - same as "show calls"
  • detailed_calls - like "show calls" but with more fields
  • detailed_bridged_calls - like "show calls" but with more fields
  • aliases - list aliases -
  • complete - list command complete tables
  • chat - list chat modules
  • management - list management?
  • modules - list modules
  • nat_map - list network address translation map
  • say - list available say modules with language supported
  • interfaces - list all interfaces
  • interface_types - list all interface types
  • tasks - list tasks
  • registrations - list user registration(s)

Tips For Showing Calls and Channels

The best way to get an understanding of all of the show calls/channels is to actually try them out. Recently (Sept 2011) there have been some additions to the show family:

  • show detailed_calls
  • show bridged_calls
  • show detailed_bridged_calls

These three take the place of simply doing "show calls". Note that show detailed_calls replaces show distinct_channels. It is similar, but gives more information. Also note that there isn't a "show detailed_channels" command, however using "show detailed_calls" will yield the same net result: you will get detailed information about one-legged calls and bridged calls by using show detailed_calls, so get used to using this new command.

Another tip: sometimes you need to gather related or specific uuids. If you set the presence_data channel variable then you can use:

show channels like foo

The like directive follows these fields:

  • uuid
  • channel name
  • caller id name
  • caller id number
  • presence_data

NOTE: presence_data must be set during bridge or originate and not after the channel is established.


Stop the FreeSWITCH program. This only works from the CLI, as an API call, you should be using 'fsctl shutdown'

Warning! Shutdown from the CLI ignores arguments and exits immediately!

Usage: fsctl shutdown [cancel|elegant|asap|restart|now]
  • cancel - discontinue a previous shutdown request.
  • elegant - wait for all traffic to stop; do not prevent new traffic.
  • asap - wait for all traffic to stop; do not allow new traffic.
  • restart - restart FreeSWITCH immediately following the shutdown.
  • now - shutdown FreeSWITCH immediately.

When giving "elegant", "asap" or "now" it's also possible to give the restart command:

Usage: fsctl shutdown [elegant|asap|now] restart


Show current status

Usage: status
freeswitch@internal> status
UP 0 years, 0 days, 1 hour, 28 minutes, 4 seconds, 208 milliseconds, 305 microseconds
FreeSWITCH is ready
4 session(s) since startup
0 session(s) 0/30                        <- Most channels to create per second .. from switch.conf.xml
1000 session(s) max                      <- Max number of sessions to allow at any given time .. from switch.conf.xml
min idle cpu 0.00/100.00                 <- Minimum idle CPU before refusing calls .. from switch.conf.xml if it's enabled.


Displays formatted time, converted to a specific timezone. See /usr/share/zoneinfo/ for the standard list of Linux timezones.

Usage: strftime_tz <timezone> [format_string]

Example: strftime_tz US/Eastern %Y-%m-%d %T


Unload external module.

Usage: unload [-f] <mod_name>


Show version of the switch

Usage: version [short]


xml_locate root: Will return all XML being used by FreeSWITCH xml_locate <section>: Will return the XML corresponding to the specified <section>

xml_locate directory
xml_locate configuration
xml_locate dialplan
xml_locate phrases
Usage: xml_locate [root | <section> | <section> <tag> <tag_attr_name> <tag_attr_val>]
Example: xml_locate directory domain name


Wrap another API command in XML.

Usage: xml_wrap <command> <args>

Call Management Commands


Deprecated. See uuid_break.


Creates a new UUID and returns it as a string.

Usage: create_uuid


Originate a new call.

   Usage: originate <call_url> <exten>|&<application_name>(<app_args>) 
   [<dialplan>] [<context>] [<cid_name>] [<cid_num>] [<timeout_sec>]


  • <call_url> URL you are calling.
    For more info on sofia SIP URL syntax see: FreeSwitch Endpoint Sofia
  • Destination, one of:
    • <exten> Destination number to enter dialplan with
    • &<application_name>(<app_args>)
      • "&" indicates what follows is an application name, not an exten
      • (<app_args>) is optional (not all applications require parameters, eg park)
      • Here is a list of valid application names that can be used here:
        park, bridge, javascript/lua/perl, playback (remove mod_native_file), and many others.
      • Note: Use single quotes to pass arguments with spaces, e.g. '&lua(test.lua arg1 arg2)'
      • Note: There is no space between & and the application name
  • <dialplan> Defaults to 'XML' if not specified.
  • <context> Defaults to 'default' if not specified.
  • <cid_name> CallerID name.
  • <cid_num> CallerID number.
  • <timeout_sec> Timeout in seconds.


These options can be used in curly braces, example: "originate {ignore_early_media=true}sofia/example/user 8334".

Options must be separated by ',', Example: "originate {ignore_early_media=true,originate_timeout=2}sofia/example/user 8334"

  • group_confirm_key
  • group_confirm_file
  • forked_dial
  • fail_on_single_reject
  • ignore_early_media
  • return_ring_ready
  • originate_retries
  • originate_retry_sleep_ms
  • origination_caller_id_name
  • origination_caller_id_number
  • originate_timeout
  • sip_auto_answer

Description of originate's related variables

Examples: So you can call a locally registered sip endpoint 300 and park the call like so (Note that the "example" profile used here must be the one your local user you want to call is registered to)

   originate sofia/example/300%pbx.internal &park()

or you could instead connect a remote sip endpoint to extension 8600

   originate sofia/example/ 8600

or you could instead connect a remote SIP endpoint to another remote extension

   originate sofia/example/ &bridge(sofia/example/

or you could even run a javascript application test.js

   originate sofia/example/ &javascript(test.js)

To run a javascript with arguments you must surround it in quotes.

   originate sofia/example/ '&javascript(test.js myArg1 myArg2)'

Setting channel variables before doing the originate

   originate {ignore_early_media=true}sofia/ 15555551212

Setting variable to send to another FS box during originate

   originate {sip_h_X-varA=111,sip_h_X-varB=222}sofia/ 15555551212

Note: you can set any channel variable, even custom ones. Use single quotes to enclose values with spaces, commas, etc.

   originate {my_own_var=my_value}sofia/ 15555551212
   originate {my_own_var='my value'}sofia/ 15555551212

If you need to fake the ringback to the originated endpoint try this:

   originate {ringback=\'%(2000,4000,440.0,480.0)\'}sofia/example/ &bridge(sofia/example/

If you need to make originate return immediately when the channel is in "Ring-Ready" state try this:

   originate {return_ring_ready=true}sofia/gateway/someprovider/919246461929 &socket( async full)

see here for more info on return_ring_ready

You can even set music on hold for the ringback if you want:

   originate {ringback=\'/path/to/music.wav\'}sofia/gateway/name/number &bridge(sofia/gateway/name/othernumber)

You can originate a call in the background (asynchronously) and playback a message with a 60 second timeout.

   bgapi originate {ignore_early_media=true,originate_timeout=60}sofia/gateway/name/number &playback(message)

You can specify the UUID of an originated call by doing the following:

  • Use create_uuid to generate a UUID to use.
  • This will allow you to kill an originated call before it is answered by using uuid_kill.
  • If you specify origination_uuid it will remain the UUID for answered call leg for the whole session.
    originate {origination_uuid=...}user/

Here's an example of originating a call to the echo conference (an external sip URL) and bridging it to a local user's phone:

   originate sofia/internal/ &bridge(user/105@default)

Here's an example of originating a call to an extension in a different context than 'default' (required for the FreePBX which uses context_1, context_2, etc.):

   originate sofia/internal/ 3001 xml context_3

You can also originate to multiple extensions as follows:

   originate user/1001,user/1002,user/1003 &park()

To put an outbound call into a conference at early media, either of these will work (they are effectively the same thing)

   originate sofia/example/ &conference(conf_uuid-TEST_CON)
   originate sofia/example/ conference:conf_uuid-TEST_CON inline
      ( See Misc._Dialplan_Tools_InlineDialplan for more detail on 'inline' Dialplans )

An example of using loopback and inline on the A-leg can be found here


Pause <uuid> media

Usage: pause <uuid> <on|off>


Answer a channel

Usage: uuid_answer <uuid>


Adjust the audio levels on a channel or mute (read/write) via a media bug.

Usage: uuid_audio <uuid> [start [read|write] [mute|level <level>]|stop]

level is in the range from -4 to 4, 0 being the default value.


Break out of media being sent to a channel. For example, if an audio file is being played to a channel, issuing uuid_break will discontinue the media and the call will move on in the dialplan, script, or whatever is controlling the call.

Usage: uuid_break <uuid> [all]

If the all flag is used then all audio files/prompts/etc. that are queued up to be played to the channel will be removed, whereas without the all flag only the currently playing file will be discontinued.


Bridge two call legs together.

Usage: uuid_bridge <uuid> <other_uuid>

uuid_bridge needs atleast any one leg to be answered.


Asynchronously execute an arbitrary dialplan application on a specific uuid. If a filename is specified then it is played into the channel(s). To execute an application use "app::args" syntax.

Usage: uuid_broadcast <uuid> <path> [aleg|bleg|both]

Execute an application on a chosen leg(s) with optional hangup afterwards:

Usage: uuid_broadcast <uuid> app[![hangup_cause]]::args [aleg|bleg|both]


 uuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e sorry.wav both
 uuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say::en\snumber\spronounced\s12345 aleg
 uuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say!::en\snumber\spronounced\s12345 aleg
 uuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say!user_busy::en\snumber\spronounced\s12345 aleg
 uuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e playback!user_busy::sorry.wav aleg


List the media bugs on channel

Usage: uuid_buglist <uuid>


Send a chat message.

-USAGE: <uuid> <text>

If the endpoint associated with the session <uuid> has a receive_event handler, this message gets sent to that session and is interpreted as an instant message.


The command was uuid_debug_audio, been changed into the current name when video options was added.

Debug media


<uuid> <read|write|both|vread|vwrite|vboth> <on|off>

Use "read" or "write" for the audio direction to debug, or "both" for both direction. And prefix with v for video.

Read Format

"R %s b=%4ld %s:%u %s:%u %s:%u pt=%d ts=%u m=%d\n"

where the values are:

  • switch_channel_get_name(switch_core_session_get_channel(session)),
  • (long) bytes,
  • my_host, switch_sockaddr_get_port(rtp_session->local_addr),
  • old_host, rtp_session->remote_port,
  • tx_host, switch_sockaddr_get_port(rtp_session->from_addr),
  • rtp_session->,
  • ntohl(rtp_session->recv_msg.header.ts),
  • rtp_session->recv_msg.header.m

Write Format

"W %s b=%4ld %s:%u %s:%u %s:%u pt=%d ts=%u m=%d\n"

where the values are:

  • switch_channel_get_name(switch_core_session_get_channel(session)),
  • (long) bytes,
  • my_host, switch_sockaddr_get_port(rtp_session->local_addr),
  • old_host, rtp_session->remote_port,
  • tx_host, switch_sockaddr_get_port(rtp_session->from_addr),
  • send_msg->,
  • ntohl(send_msg->header.ts),
  • send_msg->header.m);


Deflect an answered SIP call off of FreeSWITCH by sending the REFER method

Usage: uuid_deflect <uuid> <sip URL>

uuid_deflect waits for the final response from the far end to be reported. It returns the sip fragment from that response as the text in the FreeSWITCH response to uuid_deflect. If the far end reports the REFER was successful, then FreeSWITCH will issue a bye on the channel.


  uuid_deflect 0c9520c4-58e7-40c4-b7e3-819d72a98614


  Content-Type: api/response
  Content-Length: 30
  +OK:SIP/2.0 486 Busy Here


Displace the audio for the target <uuid> with the specified audio <file>.


  • uuid = Unique ID of this call (see 'show channels')
  • start|stop = Start/Stop this action
  • file = path to an audio source (wav, shout, etc...)
  • limit = number of seconds before terminating the displacement
  • mux = cause the original audio to be mixed together with 'file', i.e. you can still converse with the other party while the file is playing

Usage: uuid_displace <uuid> [start|stop] <file> [<limit>] [mux]


cli> uuid_displace 1a152be6-2359-11dc-8f1e-4d36f239dfb5 start /sounds/test.wav 60
cli> uuid_displace 1a152be6-2359-11dc-8f1e-4d36f239dfb5 stop /sounds/test.wav


Updates the display on a phone if the phone supports this. This works on some SIP phones right now including Polycom and Snom.

-USAGE: <uuid> [<display>]

This command makes the phone re-negotiate the codec. The SIP -> RTP Packet Size should be 0.020. If it is set to 0.030 on the SPA series phones it causes a DTMF lag. When DTMF keys are pressed on the phone they are can be seen on the fs_cli 4-6 seconds late.


Transfer each leg of a call to different destinations.

 -USAGE: <uuid> <A-dest-exten>[/<A-dialplan>][/<A-context>] <B-dest-exten>[/<B-dialplan>][/<B-context>]


Dumps all variable values for a session.

Usage: uuid_dump <uuid> [format]

Format options: XML (any others?)


Stops the process of ignoring early media, i.e. if ignore_early_media=true it stops ignoring early media and responds normally.

Usage: uuid_early_ok <uuid>


Checks whether a given UUID exists.

Usage: uuid_exists <uuid>


Flush queued DTMF digits

Usage: uuid_flush_dtmf <uuid>


Manage the audio being played into a channel from a sound file

Usage: uuid_fileman <uuid> <cmd:val>

Commands are:

  • speed:<+[step]>|<-[step]>
  • volume:<+[step]>|<-[step]>
  • pause
  • stop
  • truncate
  • restart
  • seek:<+[milliseconds]>|<-[milliseconds]> (1000ms is 1 second, 10000 for 10 seconds.)

Example to seek forward 30 seconds:

uuid_fileman 0171ded1-2c31-445a-bb19-c74c659b7d08 seek:+3000

(Or use the current channel via ${uuid}, e.g. in a bind_digit_action)


Get a variable from a channel.

Usage: uuid_getvar <uuid> <varname>


Place a call on hold.


uuid_hold <uuid>           place a call on hold
uuid_hold off <uuid>       switch off on hold
uuid_hold toggle <uuid>    toggles call-state based on current call-state


Reset a specific <uuid> channel.

Usage: uuid_kill <uuid> [cause]


Apply or change limit(s) on a specified uuid.

Usage: uuid_limit <uuid> <backend> <realm> <resource> [<max>[/interval]] [number [dialplan [context]]]

See also Limit


Reinvite FreeSWITCH out of the media path:

Usage: uuid_media [off] <uuid>

Reinvite FreeSWITCH back in:

Usage: uuid_media <uuid>


API command to tell a channel to send a re-invite with optional list of new codecs

Usage: uuid_media_reneg <uuid> <=><codec string>

Example: Adding the =PCMU makes the offered codec string absolute.


Park call

Usage: uuid_park <uuid>


Preanswer a channel.

Usage: uuid_preanswer <uuid>


Pre-process Channel

Usage: uuid_preprocess <>


Send DTMF digits to <uuid> set.

Usage: uuid_recv_dtmf <uuid> <dtmf digits>[@<tone_duration>]

Use the character w for a .5 second delay and the character W for a 1 second delay.

Default tone duration is 2000ms .


Send DTMF digits.

Usage: uuid_send_dtmf <uuid> <dtmf digits>[@<tone_duration>]

Use the character w for a .5 second delay and the character W for a 1 second delay.

Default tone duration is 2000ms .


Send info to the endpoint

Usage:  uuid_send_info <uuid>


Usage: uuid_session_heartbeat <uuid> [sched] [0|<seconds>]


Set a variable on a channel. If value is omitted, the variable is unset.

Usage: uuid_setvar <uuid> <varname> [value]


Set multiple vars on a channel.

Usage: uuid_setvar_multi <uuid> <varname>=<value>[;<varname>=<value>[;...]]


This command directs FreeSWITCH to remove itself from the SIP signaling path if it can safely do so


uuid_simplify <uuid>


Transfers an existing call to a specific extension within a <dialplan> and <context>. Dialplan may be "xml" or "directory".


uuid_transfer <uuid> [-bleg|-both] <dest-exten> [<dialplan>] [<context>]

The optional first argument will allow you to transfer both parties (-both) or only the party to whom <uuid> is talking.(-bleg)

NOTE: if the call has been bridged, and you want to transfer either sides of the call, then you will need to use <action application="set" data="hangup_after_bridge=false"/> (or the API equivalent). If it's not set, transfer doesn't really work as you'd expect, and leaves calls in limbo.

Record/Playback Commands


Record the audio associated with the given UUID into a file. The start command causes FreeSWITCH to start mixing all call legs together and saves the result as a file in the format that the file's extension dictates. (if available) The stop command will stop the recording and close the file. If media setup hasn't yet happened, the file will contain silent audio until media is available. Audio will be recorded for calls that are parked. The recording will continue through the bridged call. If the call is set to return to park after the bridge, the bug will remain on the call, but no audio is recorded until the call is bridged again. (TODO: What if media doesn't flow through FreeSWITCH? Will it re-INVITE first? Or do we just not get the audio in that case?)


uuid_record <uuid> [start|stop|mask|unmask] <path> [<limit>]

Where limit is the max number of seconds to record.

If the path is not specified on start it will default to the channel variable "sound_prefix" or FreeSWITCH base_dir when the "sound_prefix" is empty.

You may also specify "all" for path when stop is used to remove all for this uuid

"stop" command must be followed by <path> option.

"mask" will mask part of the recording. see

"unmask" will stop the masking and continue recording.

See record's related variables

Limit Commands


Reset a limit backend.


Retrieve status from a limit backend.


Retrieve usage for a given resource.


Manually decrease a resource usage by one.


Reset the interval counter to zero prior to the start of the next interval.

Misc. Commands


Execute a system command in the background.

Usage: bg_system <command>


Echo input back to the console

echo This text will appear
This text will appear


Tests whether filename exists.

file_exists filename


> file_exists /tmp/real_file
> file_exists /tmp/missing_file

Example dialplan usage:

<extension name="play-news-announcements">
  <condition expression="${file_exists(${sounds_dir}/news.wav)}" expression="true"/>
    <action application="playback" data="${sounds_dir}/news.wav"/>
    <anti-action application="playback" data="${soufnds_dir}/no-news-is-good-news.wav"/>

Note this tests whether FreeSWITCH can see the file, but the file may still be unreadable (permissions).


Checks to see if a user exists; Matches user tags found in the directory, similar to user_exists, but returns an XML representation of the user as defined in the directory (like the one shown in user_exists).

Usage: find_user_xml <key> <user> <domain>

Where key references a key specified in a directory's user tag, user represents the value of the key, and the domain is the domain the user is assigned to.


Lists Users configured in Directory


list_users [group <group>] [domain <domain>] [user <user>] [context <context>]


freeswitch@localhost> list_users group default

2000|default||default|sofia/internal/sip:2000@|techsupport|B#-Test 2000|2000
2001|default||default|sofia/internal/sip:2001@;rinstance=8e2c8b86809acf2a|techsupport|Test 2001|2001
2002|default||default|error/user_not_registered|techsupport|Test 2002|2002
2003|default||default|sofia/internal/sip:2003@|techsupport|Test 2003|2003
2004|default||default|error/user_not_registered|techsupport|Test 2004|2004


Search items can be combined:

freeswitch@localhost> list_users group default user 2004

2004|default||default|error/user_not_registered|techsupport|Test 2004|2004



Schedule an API call in the future. Usage:

   sched_api [+@]

time is the UNIX timestamp at which the command should be executed. If it is prefixed by +, <time> specifies the number of seconds to wait before executing the command. If prefixed by @, it will execute the command periodically every <time> seconds; for the first time it will be executed after <time> seconds.
group_name will be the value of "Task-Group" in generated events. "none" is the proper value for no group.
command_string is the command executed

Scheduled task or group of tasks can be revoked with sched_del or unsched_api.

You could put "&" symbol at the end of the line to make command to be executed in its own thread.


   sched_api +1800 none originate sofia/internal/1000%${sip_profile} &echo()
   sched_api @600 check_sched log Periodic task is running...


Play a <path> file to a specific <uuid> call in the future. Usage:

   sched_broadcast [+]<time> <uuid> <path> [aleg|bleg|both]

Schedule execution of an application on a chosen leg(s) with optional hangup: Usage:

   sched_broadcast [+]<time> <uuid> app[![hangup_cause]]::args [aleg|bleg|both]

time is the UNIX timestamp at which the command should be executed (or if it is prefixed by +, the number of seconds to wait before executing the command)


   sched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e commercial.wav both
   sched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e say::en\snumber\spronounced\s12345 aleg


Removes a prior scheduled group or task ID Usage:

   sched_del <group_name|task_id>

The one argument can either be a group of prior scheduled tasks or the returned task-id from sched_api.


   sched_del my_group
   sched_del 2


Schedule a running call to hangup.

Usage: sched_hangup [+]<time> <uuid> [<cause>]

Note: sched_hangup +0 is the same as uuid_kill


Schedule a transfer for a running call.

Usage: sched_transfer [+]<time> <uuid> <extension> [<dialplan>] [<context>]


Executes a STUN lookup. Usage:

   stun <stunserver>[:port]




Execute a system command.

Usage: system <command>

The command is passed to the system shell, where it may be expanded or interpreted in ways you don't expect. This can lead to security bugs if you're not careful. For example, the following command is dangerous:

 <action application="system" data="log_caller_name ${caller_id_name}" />

If a malicious remote caller somehow sets their caller ID name to "; rm -rf /", you would unintentionally be executing this shell command:

 log_caller_name; rm -rf /


Time test.

Usage: time_test <mss> [count]

Runs a test to see how bad timer jitter is. It runs the test count times (default 10) and tries to sleep for mss microseconds. It returns the actual timer duration along with an average.


time_test 100 5

test 1 sleep 100 99
test 2 sleep 100 97
test 3 sleep 100 96
test 4 sleep 100 97
test 5 sleep 100 102
avg 98


Timer test.

Usage: timer_test <10|20|40|60|120> [<1..200>] [<timer_name>]

Runs a test to see how bad timer jitter is. Unlike time_test, this uses the actual freeswitch timer infrastructure to do the timer test and exercises the timers used for call processing.

First argument is the timer interval. Second is the count. Third is the timer name ("show timers" will give you a list)


timer_test 20 3

Avg: 16.408ms Total Time: 49.269ms

2010-01-29 12:01:15.504280 [CONSOLE] mod_commands.c:310 Timer Test: 1 sleep 20 9254
2010-01-29 12:01:15.524351 [CONSOLE] mod_commands.c:310 Timer Test: 2 sleep 20 20042
2010-01-29 12:01:15.544336 [CONSOLE] mod_commands.c:310 Timer Test: 3 sleep 20 19928


Start Tone Detection on a channel.

Usage: tone_detect <uuid> <key> <tone_spec> [<flags> <timeout> <app> <args>] <hits>


Unschedule an api command.

Usage: unsched_api <task_id>


Usage: url_decode <string>

Url decode a string.


Url encode a string.

Usage: url_encode <string>


Retrieves user information (parameters or variables) as defined in the directory.

Usage: user_data <user>@<domain> [attr|var|param] <name>

Where user is the user's id, domain is the user's domain, var|param specifies whether the info we're requesting is a variable/parameter, and the name is the name (key) of the variable.


   user_data 1000@ param password

will return a result of 1234, and

   user_data 1000@ var accountcode

will return a result of 1000 from the example user shown in user_exists, and

   user_data 1000@ attr id

will return the user's actual alphanumeric ID (i.e. "john") when number-alias="1000" was set as an attribute for that user.


Checks to see if a user exists; Matches user tags found in the directory and returns either true/false:

Usage: user_exists <key> <user> <domain>

Where key references a key specified in a directory's user tag, user represents the value of the key, and the domain is the domain the user is assigned to.


   user_exists id 1000

will return true where there exists in the directory a user with a key called id whose value equals 1000:

    <user id="1000" randomvar="45">
          <param name="password" value="1234"/>
          <param name="vm-password" value="1000"/>
          <variable name="accountcode" value="1000"/>
          <variable name="user_context" value="default"/>
          <variable name="effective_caller_id_name" value="Extension 1000"/>
          <variable name="effective_caller_id_number" value="1000"/>

In the above example, we also could have tested for randomvar:

   user_exists randomvar 45

And we would have received the same results, but:

   user_exists accountcode 1000


   user_exists password 1000

Would have returned false.

See Also