See below.

API/Event Interfaces

Scripting Interfaces

From the Dialplan

An API command can be called from the dialplan. Example:Invoke API Command From DialplanOther examples:Other Dialplan API Command ExamplesAPI commands with multiple arguments usually have the arguments separated by a space:Multiple Arguments

Dialplan UsageIf you are calling an API command from the dialplan make absolutely certain that there isn’t already a dialplan application that gives you the functionality you are looking for. See mod_dptools for a list of dialplan applications, they are quite extensive.

Extraction Script

Mitch Capper wrote a Perl script to extract commands from mod_commands source code. It’s tailored specifically for extracting from mod_commands but should work for most other files.Extraction Perl Script#!/usr/bin/perluse strict;open (fl,“src/mod/applications/mod_commands/mod_commands.c”);my $cont;{    local $/ = undef;    $cont = ;}close fl;my %DEFINES;my $reg_define = qr/[A-Za-z0-9_]+/;my $reg_function = qr/[A-Za-z0-9_]+/;my $reg_string_or_define = qr/(?:(?:$reg_define)|(?:"[^"]*"))/;

#load defineswhile ($cont =~ /                    ^\s* #define \s+ ($reg_define) \s+ "([^"]*)"                /mgx){    warn “$1 is #defined multiple times” if ($DEFINES{$1});    $DEFINES{$1} = $2;}

sub resolve_str_or_define($){    my ($str) = @_;    if ($str =~ s/^"// && $str =~ s/"$//){ #if starts and ends with a quote strip them off and return the str        return $str;    }    warn “Unable to resolve define: $str” if (! $DEFINES{$str});    return $DEFINES{$str};}#parse commandswhile ($cont =~ /                    SWITCH_ADD_API \s* ( ([^,]+) #interface $1                    ,\s* ($reg_string_or_define) # command $2                    ,\s* ($reg_string_or_define) # command description $3                    ,\s* ($reg_function) # function $4                    ,\s* ($reg_string_or_define) # usage $5                    \s*);                /sgx){        my ($interface,$command,$descr,$function,$usage) = ($1,$2,$3,$4,$5);        $command = resolve_str_or_define($command);        $descr = resolve_str_or_define($descr);        $usage = resolve_str_or_define($usage);        warn “Found a not command interface of: $interface for command: $command” if ($interface ne “commands_api_interface”);        print “$command – $descr – $usage\n”;}

Core Commands

Implemented in of Returned DataResults 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 Access Control ListUsage: acl <list_name>


Alias: a means to save some keystrokes on commonly used commands.Usage: alias add | del [|*]Example:freeswitch> alias add reloadall reloadacl reloadxml+OKfreeswitch> alias add unreg sofia profile internal flush_inbound_reg+OKYou can add aliases that persist across restarts using the stickyadd argument:freeswitch> alias stickyadd reloadall reloadacl reloadxml+OKOnly really works from the console, not fs_cli.


Execute an API command in a thread.Usage: bgapi [ ]


Complete.Usage: complete add |del [|*]


Evaluate a conditional expression.Usage: cond  ?  : Operators supported by are:

  • == (equal to)
  • != (not equal to)
  •   (greater than)

  • = (greater than or equal to)

  • <  (less than)
  • <= (less than or equal to)

How are values compared?

  • two strings are compared as strings
  • two numbers are compared as numbers
  • a string and a number are compared as strlen(string) and numbers

For example, foo == 3 evaluates to true, and foo == three to false.

 Examples (click to expand)

Example:Return true if first value is greater than the secondcond 5 > 3 ? true : falsetrueExample in dialplan:Slightly more complex example:

Note about syntaxThe whitespace around the question mark and colon are required since FS-5945. Before that, they were optional. If the spaces are missing, the cond function will return -ERR.


Check if a FreeSWITCH domain exists.Usage: domain_exists


Eval (noop). Evaluates a string, expands variables. Those variables that are set only during a call session require the uuid of the desired session or else return “-ERR no reply”.Usage: eval [uuid: ]Examples:eval ${domain} Hello, World!Hello, World!eval uuid:e72aff5c-6838-49a8-98fb-84c90ad840d9 ${channel-state}CS_EXECUTE


Execute an API command with variable expansion.Usage: expand [uuid: ] Example:expand originate sofia/internal/1001%${domain} 9999In 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 control messages to FreeSWITCH.USAGE: fsctl   [   api_expansion [on|off] |   calibrate_clock |   debug_level [level] |   debug_sql |   default_dtmf_duration [n] |   flush_db_handles |   hupall |   last_sps |   loglevel [level] |   max_dtmf_duration [n] |   max_sessions [n] |   min_dtmf_duration [n] |   min_idle_cpu [d] |   pause [inbound|outbound] |   pause_check [inbound|outbound] |   ready_check |   reclaim_mem |   recover |   resume [inbound|outbound] |   save_history |   send_sighup |   shutdown [cancel|elegant|asap|now|restart] |   shutdown_check |   sps |   sps_peak_reset |   sql [start] |   sync_clock |   sync_clock_when_idle |   threaded_system_exec |   verbose_events [on|off]   ]

fsctl arguments


Usage: fsctl api_expansion [on|off]Toggles API expansion. With it off, no API functions can be expanded inside channel variables like ${show channels} This is a specific security mode that is not often used.


Usage: fsctl calibrate_clockRuns an algorithm to compute how long it actually must sleep in order to sleep for a true 1ms.  It’s only useful in older kernels that don’t have timerfd.  In those older kernels FS auto detects that it needs to do perform that computation. This command just repeats the calibration.

**debug_level **

Usage: fsctl debug_level [level]Set the amount of debug information that will be posted to the log. 1 is less verbose while 9 is more verbose. Additional debug messages will be posted at the ALERT loglevel.0 - fatal errors, panic1 - critical errors, minimal progress at subsystem level2 - non-critical errors3 - warnings, progress messages5 - signaling protocol actions (incoming packets, …)7 - media protocol actions (incoming packets, …)9 - entering/exiting functions, very verbatim progress


Usage: fsctl debug_sqlToggle core SQL debugging messages on or off each time this command is invoked. Use with caution on busy systems. In order to see all messages issue the “logelevel debug” command on the fs_cli interface.


Usage: fsctl default_dtmf_duration [int]int = number of clock ticksExample:fsctl default_dtmf_duration 2000This example sets the default_dtmf_duration switch parameter to 250ms. The number is specified in clock ticks (CT) where duration (milliseconds) = CT / 8 or CT = duration * 8The 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 is bounded on the lower end by min_dtmf_duration and on the upper end by max_dtmf_duration. So max_dtmf_duration >= default_dtmf_duration >= min_dtmf_duration . This value can be set persistently in switch.conf.xmlTo check the current value:fsctl default_dtmf_duration 0FS recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.


Usage: fsctl flush_db_handlesFlushes cached database handles from the core db handlers. FreeSWITCH reuses db handles whenever possible, but a heavily loaded FS system can accumulate a large number of db handles during peak periods while FS continues to allocate new db handles to service new requests in a FIFO manner. “fsctl flush_db_handles” closes db connections that are no longer needed to avoid exceeding connections to the database server.


Usage: fsctl hupall <clearing_type> dialed_ext Disconnect existing calls to a destination and post a clearing cause.For example, to kill an active call with normal clearing and the destination being extension 1000:fsctl hupall normal_clearing dialed_ext 1000


Usage: fsctl last_spsQuery the actual sessions-per-second.fsctl last_sps+OK last sessions per second: 723987253(Your mileage might vary.)


Usage: fsctl loglevel [level]Filter much detail the log messages will contain when displayed on the fs_cli interface. See mod_console for legal values of “level” and further discussion.The available loglevels can be specified by number or name:0 - CONSOLE1 - ALERT2 - CRIT3 - ERR4 - WARNING5 - NOTICE6 - INFO7 - DEBUG


Usage: fsctl max_sessions [int]Set how many simultaneous call sessions FS will allow. This value can be ascertained by load testing, but is affected by processor speed and quantity, network and disk bandwidth, choice of codecs, and other factors. See switch.conf.xml for the persistent setting max-sessions.


Usage: fsctl max_dtmf_duration [int]Default = 192000 clock ticksExample:fsctl max_dtmf_duration 80000This example sets the max_dtmf_duration switch parameter to 10,000ms (10 seconds). The integer is specified 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 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 set persistently in switch.conf.xml as max-dtmf-duration.To query the current value:fsctl max_dtmf_duration 0FreeSWITCH recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.


Usage: fsctl min_dtmf_duration [int]Default = 400 clock ticksExample:fsctl min_dtmf_duration 800This example sets the min_dtmf_duration switch parameter to 100ms. The integer is specified in clock ticks (CT) where CT / 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 set persistently in switch.conf.xml as min-dtmf-duration.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 DTMF events must be encoded in the audio stream. This means that other devices down the line (possibly a PBX or IVR that you are calling) might not hear DTMF tones that are long enough to decode and so will ignore them 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 0FreeSWITCH recognizes a duration of 0 as a status check. Instead of setting the value to 0, it simply returns the current value.


Usage: fsctl min_idle_cpu [int]Allocates the minimum percentage of CPU idle time available to other processes to prevent FreeSWITCH from consuming all available CPU cycles.Example:fsctl min_idle_cpu 10This allocates a minimum of 10% CPU idle time which is not available for processing by FS. Once FS reaches 90% CPU consumption it will respond with cause code 503 to additional SIP requests until its own usage drops below 90%, while reserving that last 10% for other processes on the machine. 


Usage: fsctl pause [inbound|outbound]Pauses the ability to receive inbound or originate outbound calls, or both directions if the keyword is omitted. Executing fsctl pause inbound will also prevent registration requests from being processed. Executing fsctl pause outbound will result in the Critical log message “The system cannot create any outbound sessions at this time” in the FS log.Use resume with the corresponding argument to restore normal operation.


Usage: fsctl pause_check [inbound|outbound]Returns true if the specified mode is active.Examples:fsctl pause_check inboundtrueindicates that inbound calls and registrations are paused. Use fsctl resume inbound to restore normal operation.fsctl pause_checktrueindicates that both inbound and outbound sessions are paused. Use fsctl resume to restore normal operation.


Usage: fsctl ready_checkReturns true if the system is in the ready state, as opposed to awaiting an elegant shutdown or other not-ready state.


Usage: fsctl reclaim_mem


Usage: fsctl recoverSends an endpoint–specific recover command to each channel detected as recoverable. This replaces “sofia recover” and makes it possible to have multiple endpoints besides SIP implement recovery.


Usage: fsctl resume [inbound|outbound]Resumes normal operation after pausing inbound, outbound, or both directions of call processing by FreeSWITCH.Example:fsctl resume inbound+OKResumes processing of inbound calls and registrations. Note that this command always returns +OK, but the same keyword must be used that corresponds to the one used in the pause command in order to take effect.


Usage: fsctl save_historyWrite out the command history in anticipation of executing a configuration that might crash FS. This is useful when debugging a new module or script to allow other developers to see what commands were executed before the crash.


Usage: fsctl send_sighupDoes the same thing that killing the FS process with -HUP would do without having to use the UNIX kill command. Useful in environments like Windows where there is no kill command or in cron or other scripts by using fs_cli -x “fsctl send_sighup” where the FS user process might not have privileges to use the UNIX kill command.


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

  • cancel - discontinue a previous shutdown request.
  • elegant - wait for all traffic to stop, while allowing new traffic.
  • asap - wait for all traffic to stop, but deny new traffic.
  • now - shutdown FreeSWITCH immediately.
  • restart - restart FreeSWITCH immediately following the shutdown.

When giving “elegant”, “asap” or “now” it’s also possible to add the restart command:


Usage: fsctl shutdown_checkReturns true if FS is shutting down, or shutting down and restarting.


Usage: fsctl sps [int]This changes the sessions-per-second limit from the value initially set in switch.conf


Usage: fsctl sync_clockFreeSWITCH will not trust the system time. It gets one sample of system time when it first starts and uses the monotonic clock after that moment. You can sync it back to the current value of the system’s real-time clock with fsctl sync_clockNote: fsctl sync_clock immediately takes effect, which can affect the times on your CDRs. You can end up underbilling/overbilling, or even calls hungup before they originated. e.g. if FS clock is off by 1 month, then your CDRs will show calls that lasted for 1 month!See fsctl sync_clock_when_idle which is much safer.


Usage: fsctl sync_clock_when_idleSynchronize the FreeSWITCH clock to the host machine’s real-time clock, but wait until there are 0 channels in use. That way it doesn’t affect any CDRs.


Usage: fsctl verbose_events [on|off]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.See switch.conf.xml for the persistent setting of verbose-channel-events.


Gets the value of a global variable. If the parameter is not provided then it gets all the global variables.Usage: global_getvar []


Sets the value of a global variable.Usage: global_setvar =Example:global_setvar outbound_caller_id=2024561000


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 | (the pipe character)+A (default) will return them in a parallel fashion separated by , (comma)+E will return them in a enterprise fashion separated by :_: (colon underscore colon).There is no space between the domain and the optional flag. See Groups in the XML User Directory for more information.Please note: If you need to have outgoing user variables set in leg B, 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 the default group of the user. This way group_call will return user/101 and user/ would set all your user variables to the leg B channel.The B leg receives a new variable, dialed_group, containing the full group name.


Show help for all the API commands.Usage: help


Performs a DNS lookup on a host name.Usage: host_lookup


Disconnect existing channels.Usage: hupall [ ]All channels with set to will be disconnected with code.Example:originate {foo=bar}sofia/internal/,sofia/internal/ &parkhupall normal_clearing foo barTo hang up all calls on the switch indiscriminately:hupall system_shutdown


Determine if a user is a member of a group.Usage: in_group [@] <group_name>


See if an IP is a LAN address.Usage: is_lan_addr


JSON APIUsage: json {“command” : “…”, “data” : “…”}Example> json {“command” : “status”, “data” : “”} {“command”:“status”,“data”:"",“status”:“success”,“response”:{“systemStatus”:“ready”,“uptime”:{“years”:0,“days”:20,“hours”:20,“minutes”:37,“seconds”:4,“milliseconds”:254,“microseconds”:44},“version”:“1.6.9 -16-d574870 64bit”,“sessions”:{“count”:{“total”:132,“active”:0,“peak”:2,“peak5Min”:0,“limit”:1000},“rate”:{“current”:0,“max”:30,“peak”:2,“peak5Min”:0}},“idleCPU”:{“used”:0,“allowed”:99.733333},“stackSizeKB”:{“current”:240,“max”:8192}}}


Load external moduleUsage: load <mod_name>Example:load mod_v8


Return MD5 hash for the given input dataUsage: md5 hash-keyExample:md5 freeswitch-is-awesome765715d4f914bf8590d1142b6f64342e


Check if module is loaded.Usage: module_exists Example:module_exists mod_event_sockettrue


Sleep for x number of millisecondsUsage: msleep


Manage Network Address Translation mapping.Usage: nat_map [status|reinit|republish] | [add|del] [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 routes or have changed your home 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 whether 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 the public IP 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 network interfaces with unique IP addresses defined in sip profiles using the same port, nat_map will get confused when it tries to map the same ports for multiple profiles. Set up a static mapping between the public address and port and the private address and port in the sip_profiles to avoid this problem.


Evaluate a regex (regular expression).Usage: regex |[|][|(n|b)]regex m://[/][/(n|b)]regex m:~~[~][~(n|b)]This command behaves differently depending upon whether or not a substitution string and optional flag is supplied:

  • If a subst is not supplied, regex returns either “true” if the pattern finds a match or “false” if not.
  • If a subst is supplied, regex returns the subst value on a true condition.
  • If a subst is supplied, on a false (no pattern match) condition regex returns:
    • the source string with no flag;
    • with the n flag regex returns null which forces the response “-ERR no reply” from regex;
    • with the b flag regex returns “false”

The regex delimiter defaults to the | (pipe) character. The delimiter may be changed to ~ (tilde) or / (forward slash) by prefixing the regex with m:Examples: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 “-ERR no reply” (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 <mod_name>


Reload Access Control Lists after modifying them in autoload_configs/acl.conf.xml and as defined in extensions in the user directory conf/directory/*.xmlUsage: reloadacl [reloadxml]


Reload conf/freeswitch.xml settings after modifying configuration files.Usage: reloadxml


Display various reports, VERY useful for troubleshooting and confirming proper configuration of FreeSWITCH. Arguments can not be abbreviated, they must be specified fully.Usage: show [   aliases |   api |   application |   bridged_calls |   calls [count] |   channels [count|like ] |   chat |   codec |   complete |   detailed_bridged_calls |   detailed_calls |   dialplan |   endpoint |   file |   interface_types |   interfaces |   limits   management |   modules |   nat_map |registrations |   say |   tasks |   timer |   ] [as xml|as delim ]XML formatted:show foo as xmlChange delimiter:show foo as delim |

  • aliases – list defined command aliases
  • api – list API commands exposed by loadable modules
  • application – list applications exposed by loadable modules, notably mod_dptools
  • bridged_calls – deprecated, use “show calls”
  • calls [count] – list details of currently active calls; the keyword “count” eliminates the details and only prints the total count of calls
  • channels [count|like ] – list current channels; see Channels vs Calls
    • count – show only the count of active channels, no details
    • like – filter results to include only channels that contain in uuid, channel name, cid_number, cid_name, presence data fields.
  • chat – list chat interfaces
  • codec – list codecs that are currently loaded in FreeSWITCH
  • complete – list command argument completion tables
  • detailed_bridged_calls – same as “show detailed_calls”
  • detailed_calls – like “show calls” but with more fields
  • dialplan – list dialplan interfaces
  • endpoint – list endpoint interfaces currently available to FS
  • file – list supported file format interfaces
  • interface_types – list all interface types with a summary count of each type of interface available
  • interfaces – enumerate all available interfaces by type, showing the module which exposes each interface
  • limits – list database limit interfaces
  • management – list management interfaces
  • module – enumerate modules and the path to each
  • nat_map – list Network Address Translation map
  • registrations – enumerate user extension registrations
  • say – enumerate available TTS (text-to-speech) interface modules with language supported
  • tasks – list FS tasks
  • timer – list timer modules

Tips For Showing Calls and Channels

The best way to get an understanding of all of the show calls/channels is to use them and observe the results. To display more fields:

  • show detailed_calls
  • show bridged_calls
  • show detailed_bridged_calls

These three take the expand on information shown by “show calls”. Note that “show detailed_calls” replaces “show distinct_channels”. It provides similar, but more detailed, information. Also note that there is no “show detailed_channels” command, however using “show detailed_calls” will yield the same net result: FreeSWITCH lists detailed information about one-legged calls and bridged calls by using “show detailed_calls”, which can be quite useful while configuring and troubleshooting FS.Filtering ResultsTo filter only channels matching a specific uuid or related to a specific call, set the presence_data channel variable in the bridge or originate application to a unique string. Then you can use:show channels like footo list only those channels of interest. The like directive filters on 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.Usage: shutdownThis only works from the console. To shutdown FS from an API call or fs_cli, you should use “fsctl shutdown” which offers a number of options.Shutdown from the console ignores arguments and exits immediately!


Show current FS status. Very helpful information to provide when asking questions on the mailing list or irc channel.Usage: statusfreeswitch@internal> statusUP 17 years, 20 days, 10 hours, 10 minutes, 31 seconds, 571 milliseconds, 721 microsecondsFreeSWITCH (Version 1.5.8b git 87751f9 2013-12-13 18:13:56Z 32bit) is ready 53987253 session(s) since startup 127 session(s) - peak 127, last 5min 253 55 session(s) per Sec out of max 60, peak 55, last 5min 253 1000 session(s) max min idle cpu 0.00/97.71


Displays formatted time, converted to a specific timezone. See /usr/share/zoneinfo/ for the standard list of Linux timezones.Usage: strftime_tz [format_string]Example:strftime_tz US/Eastern %Y-%m-%d %T


Unload external module.Usage: unload <mod_name>


Show version of the switchUsage: version [short]Examples:freeswitch@internal> versionFreeSWITCH Version 1.5.8b+git~20131213T181356Z~87751f9eaf~32bit (git 87751f9 2013-12-13 18:13:56Z 32bit)freeswitch@internal> version short1.5.8b


Write active xml tree or specified branch to stdout.Usage: xml_locate [root | | <tag_attr_name> <tag_attr_val>]xml_locate root will return all XML being used by FreeSWITCHxml_locate : Will return the XML corresponding to the specified xml_locate directoryxml_locate configurationxml_locate dialplanxml_locate phrasesExample:xml_locate directory domain name example.comxml_locate configuration configuration name ivr.conf


Wrap another API command in XML.Usage: xml_wrap

Call Management Commands


Deprecated. See uuid_break.


Creates a new UUID and returns it as a string.Usage: create_uuid


Originate a new call.Usageoriginate <call_url> |&<application_name>(<app_args>) [] [] [<cid_name>] [<cid_num>] [<timeout_sec>]

FreeSWITCH will originate a call to <call_url> as Leg A. If that leg supervises within 60 seconds FS will continue by searching for an extension definition in the specified dialplan for or else execute the application that follows the & along with its arguments.Originate Arguments


  • <call_url> URL you are calling. For more info on sofia SIP URL syntax see: FreeSwitch Endpoint Sofia
  • Destination, one of:
    • Destination number to search in dialplan; note that registered extensions will fail this way, use &bridge(user/xxxx) instead
    • &<application_name>(<app_args>)
      • “&” indicates what follows is an application name, not an exten
      • (<app_args>) is optional (not all applications require parameters, e.g. park)
      • The most commonly used application names include:park, bridge, javascript/lua/perl, playback (remove mod_native_file).
      • 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
  • Defaults to ‘XML’ if not specified.
  • Defaults to ‘default’ if not specified.
  • <cid_name> CallerID name to send to Leg A.
  • <cid_num> CallerID number to send to Leg A.
  • <timeout_sec> Timeout in seconds; default = 60 seconds.

Originate Variables


These variables can be prepended to the dial string inside curly braces and separated by commas. Example:originate {sip_auto_answer=true,return_ring_ready=false}user/1001 9198Variables within braces must be separated by a comma.

  • group_confirm_key
  • group_confirm_file
  • forked_dial
  • fail_on_single_reject
  • ignore_early_media - must be defined on Leg B in bridge or originate command to stop remote ringback from being heard by Leg A
  • 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 

Originate Examples


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 to which 300 is registered. Also note the use of % instead of @ to indicate that it is a registered extension.originate sofia/example/300%pbx.internal &park()Or you could instead connect a remote sip endpoint to extension 8600originate sofia/example/ 8600Or you could instead connect a remote SIP endpoint to another remote extensionoriginate sofia/example/ &bridge(sofia/example/ you could even run a Javascript application test.jsoriginate sofia/example/ &javascript(test.js)To run a javascript with arguments you must surround it in single quotes.originate sofia/example/ ‘&javascript(test.js myArg1 myArg2)’Setting channel variables to the dial stringoriginate {ignore_early_media=true}sofia/ 15555551212Setting SIP header variables to send to another FS box during originateoriginate {sip_h_X-varA=111,sip_h_X-varB=222}sofia/ 15555551212Note: 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/ 15555551212originate {my_own_var=‘my value'}sofia/ 15555551212If 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/ specify a parameter to the Leg A call and the Leg B bridge application:originate {‘origination_caller_id_number=2024561000’}sofia/gateway/ &bridge([’effective_caller_id_number=7036971379’]sofia/gateway/

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’)More info on return_ring_readyYou 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/siptoshore/12425553741)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 the answered call leg for the whole session.

originate {origination_uuid=...}user/’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_3You 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 inlineSee mod_dptools: Inline Dialplan for more detail on ‘inline’ DialplansAn example of using loopback and inline on the A-leg can be found in this mailing list post 


Pause playback of recorded media that was started with uuid_broadcast.Usagepause <on|off>Turning pause “on” activates the pause function, i.e. it pauses the playback of recorded media. Turning pause “off” deactivates the pause function and resumes playback of recorded media at the same point where it was paused.Note: always returns -ERR no reply when successful; returns -ERR No such channel! when uuid is invalid.


Answer a channelUsageuuid_answer See Also


Adjust the audio levels on a channel or mute (read/write) via a media bug.Usageuuid_audio [start [read|write] [[mute|level] ]|stop] is in the range from -4 to 4, 0 being the default value.Level is required for both mute|level params:freeswitch@internal> uuid_audio 0d7c3b93-a5ae-4964-9e4d-902bba50bd19 start write mute freeswitch@internal> uuid_audio 0d7c3b93-a5ae-4964-9e4d-902bba50bd19 start write level (This command behaves funky. Requires further testing to vet all arguments. - JB)See Also


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 [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 stopped and removed from the queue, otherwise only the currently playing media will be stopped.


Bridge two call legs together.Usageuuid_bridge <other_uuid>uuid_bridge needs at least any one leg to be in the answered state. If, for example, one channel is parked and another channel is actively conversing on a call, executing uuid_bridge on these 2 channels will drop the existing call and bridge together the specified channels.


Execute an arbitrary dialplan application, typically playing a media file, 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.Usageuuid_broadcast [aleg|bleg|both]Execute an application on a chosen leg(s) with optional hangup afterwards:Usageuuid_broadcast app[![hangup_cause]]::args [aleg|bleg|both]Examples:Exampleuuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e sorry.wav bothuuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say::en\snumber\spronounced\s12345 aleguuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say!::en\snumber\spronounced\s12345 aleguuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e say!user_busy::en\snumber\spronounced\s12345 aleguuid_broadcast 336889f2-1868-11de-81a9-3f4acc8e505e playback!user_busy::sorry.wav aleg


List the media bugs on channel. Output is formatted as XML.Usage



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


Debug media, either audio or video.Usageuuid_debug_media <read|write|both|vread|vwrite|vboth> <on|off>Use “read” or “write” for the audio direction to debug, or “both” for both directions. And prefix with v for video media.uuid_debug_media emits a HUGE amount of data. If you invoke this command from fs_cli, be prepared.

Example outputR sofia/internal/1003@ b= 172 pt=0 ts=2981605109 m=0W sofia/internal/1003@ b= 172 pt=0 ts=12212960 m=0R sofia/internal/1003@ b= 172 pt=0 ts=2981605269 m=0W sofia/internal/1003@ b= 172 pt=0 ts=12213120 m=0

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 methodUsage: uuid_deflect 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.Exampleuuid_deflect 0c9520c4-58e7-40c4-b7e3-819d72a98614 sip:info@example.netResponse:Content-Type: api/responseContent-Length: 30+OK:SIP/2.0 486 Busy Here


Displace the audio for the target with the specified audio .Usage: uuid_displace [start|stop] [] [mux]Arguments:

  • uuid = Unique ID of this call (see ‘show channels’)
  • start|stop = Start or stop this action
  • file = path to an audio source (.wav file, shoutcast stream, etc…)
  • limit = limit number of seconds before terminating the displacement
  • mux = multiplex; mix the original audio together with ‘file’, i.e. both parties can still converse while the file is playing (if the level is not too loud)

To specify the 5th argument ‘mux’ you must specify a limit; if no time limit is desired on playback, then specify 0.Examplescli> uuid_displace 1a152be6-2359-11dc-8f1e-4d36f239dfb5 start /sounds/test.wav 60cli> 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: name|numberNote the pipe character separating the Caller ID name and Caller ID number.This command makes the phone re-negotiate the codec. The SIP -> RTP Packet Size should be 0.020 seconds. If it is set to 0.030 on the Cisco 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.Example:freeswitch@sidious> uuid_display f4053af7-a3b9-4c78-93e1-74e529658573 Fred Jones|1001+OK Success


Transfer each leg of a call to different destinations.Usage: [/][/] [/][/]


Dumps all variable values for a session.Usage: uuid_dump [format]Format options: txt (default, may be omitted), XML, JSON, plain


Stops the process of ignoring early media, i.e. if ignore_early_media=true, this stops ignoring early media coming from Leg B and responds normally.Usage: uuid_early_ok


Checks whether a given UUID exists.Usage: uuid_exists Returns true or false.


Flush queued DTMF digitsUsage: uuid_flush_dtmf


Manage the audio being played into a channel from a sound fileUsage: uuid_fileman cmd:valCommands are:

  • speed:<+[step]>|<-[step]>
  • volume:<+[step]>|<-[step]>
  • pause (toggle)
  • stop
  • truncate
  • restart
  • seek:<+[milliseconds]>|<-[milliseconds]> (1000ms = 1 second, 10000ms = 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)The ‘pause’ argument is a toggle: the first time it is invoked it will pause playback, the second time it will resume playback.


Get a variable from a channel.Usage: uuid_getvar


Place a channel on hold.Usage:uuid_hold place a call on holduuid_hold off switch off on holduuid_hold toggle toggles call-state based on current call-state


Reset a specific channel.Usage: uuid_kill [cause]If no cause code is specified, NORMAL_CLEARING will be used.


Apply or change limit(s) on a specified uuid.Usage: uuid_limit [[/interval]] [number [dialplan [context]]]See also mod_dptools: Limit


Reinvite FreeSWITCH out of the media path:Usage: uuid_media [off] Reinvite FreeSWITCH back in:Usage: uuid_media


Tell a channel to send a re-invite with optional list of new codecs to be renegotiated.Usage: uuid_media_reneg <=>Example: Adding =PCMU makes the offered codec string absolute.


Park callUsage: uuid_park The specified channel will be parked and the other leg of the call will be disconnected.


Pre–answer a channel.Usage: uuid_preanswer See Also: Misc._Dialplan_Tools_pre_answer


Pre-process ChannelUsage: uuid_preprocess


Usage: uuid_recv_dtmf  <dtmf_data>


Send DTMF digits to Usage: uuid_send_dtmf [@<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 endpointUsage: uuid_send_info


Usage: uuid_session_heartbeat [sched] [0|]


Set a variable on a channel. If value is omitted, the variable is unset.Usage: uuid_setvar [value]


Set multiple vars on a channel.Usage: uuid_setvar_multi =[;=[;…]]


This command directs FreeSWITCH to remove itself from the SIP signaling path if it can safely do so.Usage: uuid_simplify Execute this API command to instruct FreeSWITCH™ to inspect the Leg A and Leg B network addresses. If they are both hosted by the same switch as a result of a transfer or forwarding loop across a number of FreeSWITCH™ systems the one executing this command will remove itself from the SIP and media path and restore the endpoints to their local FreeSWITCH™ to shorten the network path. This is particularly useful in large distributed FreeSWITCH™ installations.For example, suppose a call arrives at a FreeSWITCH™ box in Los Angeles, is answered, then forwarded to a FreeSWITCH™ box in London, answered there and then forwarded back to Los Angeles. The London switch could execute uuid_simplify to tell its local switch to examine both legs of the call to determine that they could be hosted by the Los Angeles switch since both legs are local to it. Alternatively, setting sip_auto_simplify to true either globally in vars.xml or as part of a dailplan extension would tell FS to perform this check for each call when both legs supervise. 


Transfers an existing call to a specific extension within a and . Dialplan may be “xml” or “directory”.Usageuuid_transfer [-bleg|-both] [] []

The optional first argument will allow you to transfer both parties (-both) or only the party to whom is talking.(-bleg). Beware that -bleg actually means “the other leg”, so when it is executed on the actual B leg uuid it will transfer the actual A leg that originated the call and disconnect the actual B leg.NOTE: if the call has been bridged, and you want to transfer either side of the call, then you will need to use (or the API equivalent). If it’s not set, transfer doesn’t really work as you’d expect, and leaves calls in limbo.And more examples see Inline Dialplan


Send hold indication upstream:Usageuuid_phone_event hold|talk

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?)Usage:uuid_record [start|stop|mask|unmask] []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 option.“mask” will mask with silence part of the recording beginning when the mask argument is executed by this command. see“unmask” will stop the masking and continue recording live audio normally.See record’s related variablesyou will also want to see mod_dptools: record_session

Limit Commands

More information is available at 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.

Miscellaneous Commands


Execute a system command in the background.Usage: bg_system


Echo input back to the consoleUsage: echo Example:echo This text will appearThis text will appear


Tests whether filename exists.file_exists filenameExamples:freeswitch> file_exists /tmp/real_filetrue

freeswitch> file_exists /tmp/missing_filefalseExample dialplan usage:file_exists example

file_exists tests whether FreeSWITCH can see the file, but the file may still be unreadable because of restrictive 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 references a key specified in a directory’s user tag represents the value of the key is the domain to which the user is assigned.


Lists Users configured in DirectoryUsage:list_users [group ] [domain ] [user ] [context ]Examples:freeswitch@localhost> list_users group default

userid|context|domain|group|contact|callgroup|effective_caller_id_name|effective_caller_id_number2000|default||default|sofia/internal/sip:2000@|techsupport|B#-Test 2000|20002001|default||default|sofia/internal/sip:2001@;rinstance=8e2c8b86809acf2a|techsupport|Test 2001|20012002|default||default|error/user_not_registered|techsupport|Test 2002|20022003|default||default|sofia/internal/sip:2003@|techsupport|Test 2003|20032004|default||default|error/user_not_registered|techsupport|Test 2004|2004

+OKSearch filters can be combined:freeswitch@localhost> list_users group default user 2004

userid|context|domain|group|contact|callgroup|effective_caller_id_name|effective_caller_id_number2004|default||default|error/user_not_registered|techsupport|Test 2004|2004



Schedule an API call in the future.Usage:sched_api [+@] <group_name> <command_string>[&] is the UNIX timestamp at which the command should be executed. If it is prefixed by +, specifies the number of seconds to wait before executing the command. If prefixed by @, it will execute the command periodically every seconds; for the first instance it will be executed after seconds.<group_name> will be the value of “Task-Group” in generated events. “none” is the proper value for no group. If set to UUID of channel (example: ${uuid}), task will automatically be unscheduled when channel hangs up.<command_string> is the command to execute at the scheduled time.A scheduled task or group of tasks can be revoked with sched_del or unsched_api.You could append the “&” symbol to the end of the line to executed this command in its own thread.Example:sched_api +1800 none originate sofia/internal/1000%${sip_profile} &echo()sched_api @600 check_sched log Periodic task is running…sched_api +10 ${uuid} chat verto|||Hello World


Play a file to a specific call in the future.Usage:sched_broadcast [[+]|@time] [aleg|bleg|both]Schedule execution of an application on a chosen leg(s) with optional hangup:sched_broadcast [+] app[![hangup_cause]]::args [aleg|bleg|both] is the UNIX timestamp at which the command should be executed. If it is prefixed by +, specifies the number of seconds to wait before executing the command. If prefixed by @, it will execute the command periodically every seconds; for the first instance it will be executed after seconds.Examples:sched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e commercial.wav bothsched_broadcast +60 336889f2-1868-11de-81a9-3f4acc8e505e say::en\snumber\spronounced\s12345 aleg


Removes a prior scheduled group or task IDUsage: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_transfer, sched_hangup and sched_broadcast commands add new tasks with group names equal to the channel UUID. Thus, sched_del with the channel UUID as the argument will remove all previously scheduled hangups, transfers and broadcasts for this channel.Examples:sched_del my_groupsched_del 2


Schedule a running call to hangup.Usage:sched_hangup [+] []sched_hangup +0 is the same as uuid_kill


Schedule a transfer for a running call.Usage:sched_transfer [+] [] []


Executes a STUN lookup.Usage:stun [:port]Example:stun


Execute a system command.Usage:system The 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:If a malicious remote caller somehow sets his caller ID name to “; rm -rf /” you would unintentionally be executing this shell command:log_caller_name; rm -rf /This would be a Bad Thing.


Runs a test to see how bad timer jitter is. It runs the test times if specified, otherwise it uses the default count of 10, and tries to sleep for mss microseconds. It returns the actual timer duration along with an average.Usage:time_test [count]Example:time_test 100 5

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


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.Usage:timer_test <10|20|40|60|120> [<1..200>] [<timer_name>]The first argument is the timer interval.The second is the number of test iterations.The third is the timer name; “show timers” will give you a list.Example: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 92542010-01-29 12:01:15.524351 [CONSOLE] mod_commands.c:310 Timer Test: 2 sleep 20 200422010-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 <tone_spec> [ ] is required when this is executed as an api call; as a dialplan app the uuid is implicit as part of the channel variables is an arbitrary name that identifies this tone_detect instance; required<tone_spec> frequencies to detect; required ‘r’ or ‘w’ to specify which direction to monitor duration during which to detect tones;0 = detect forever+time = number of milliseconds after tone_detect is executedtime = absolute time to stop in seconds since The Epoch (1 January, 1970) FS application to execute when tone_detect is triggered; if app is omitted, only an event will be returned arguments to application enclosed in single quotes the number of times tone_detect should be triggered before executing the specified appOnce tone_detect returns a result, it will not trigger again until reset. Reset tone_detect by calling tone_detect with no additional arguments to reactivate the previously specified tone_detect declaration.See also


Unschedule a previously scheduled API command.Usage:unsched_api <task_id>




Url encode a string.Usage:url_encode


Retrieves user information (parameters or variables) as defined in the FreeSWITCH user directory.Usage:user_data @ <attr|var|param> is the user’s id is the user’s domain<attr|var|param> specifies whether the requested data is contained in the “variables” or “parameters” section of the user’s record is the name (key) of the variable to retrieveExamples:user_data 1000@ param passwordwill return a result of 1234, anduser_data 1000@ var accountcodewill return a result of 1000 from the example user shown in user_exists, anduser_data 1000@ attr idwill 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 references a key specified in a directory’s user tag represents the value of the key is the domain to which the user belongsExample:user_exists id 1000 return true where there exists in the directory a user with a key called id whose value equals 1000:User Directory EntryIn the above example, we also could have tested for randomvar:user_exists randomvar 45 we would have received the same true result, but:user_exists accountcode 1000 vm-password 1000 have returned false.