Mod commands
From FreeSWITCH Wiki
Contents |
Introduction
These commands can be issued via any of the following interfaces:
- CLI
- mod_event socket
- mod_xmpp event
- mod_xml_rpc socket
- any of the scripting interfaces such as mod_perl, mod_spidermonkey, mod_python, etc.
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.
For example, see: http://svn.freeswitch.org/svn/freeswitch/trunk/src/mod/endpoints/mod_portaudio/mod_portaudio.c
Core Commands
Implemented in http://svn.freeswitch.org/svn/freeswitch/trunk/src/mod/applications/mod_commands/mod_commands.c
echo
Echo's text to the console
Usage: echo <text>
fsctl
Freeswitch control messages
Usage: fsctl [ <blank> | hupall | pause | resume | shutdown | reclaim_mem | max_sessions [num] | loglevel [level] ]
load
Load external module
Usage: load <mod_name>
unload
Unload external module
Usage: unload <mod_name>
reloadxml
Reload conf/freeswitch.xml settings
Usage: reloadxml
shutdown
Stop the Freeswitch program. This only works from the CLI, as an API call, you should be using 'fsctl shutdown'
Usage: shutdown
show
Display various reports
Usage: show [ <blank> | codec | application | api | dialplan | file | timer | calls | channels ]
status
Show current status
Usage: status
sleep
Pause for a nap
Usage: sleep <sleep_ms>
strftime
Displays the current time in various formats
Usage: strftime,<format_string>
set
Sets the value of an channel variable
Usage: set <varname>=<value>
version
Show version of the switch
Usage: version
Call Management Commands
answer
Answers a call
Usage: answer <uuid>
bridge
Bridges a call to another endpoint. See Freeswitch IVR Originate for more options of what can be done in an originate url
Usage: bridge <originate_url>
uuid_broadcast
Play a <path> file to a specific <uuid> call.
Usage: uuid_broadcast <uuid> <path> [aleg|bleg|both]
execute_extension
Execute an extension in the dialplan
Usage: execute_extension <extension> <dialplan type> <context>
Example: execute_extension 300 XML localcalls
uuid_hold
Place a call on hold.
Usage: uuid_hold <uuid>, hold off <uuid>
uuid_kill
Reset a specific <uuid> channel.
Usage: uuid_kill <uuid>
uuid_media
Reinvite <uuid> bridging (B2BUA) media
Usage: uuid_media <uuid>
originate
Originate a new call.
Usage: originate <call_url> <exten>|&<application_name>(<app_args>) [<dialplan>] [<context>] [<cid_name>] [<cid_num>] [<timeout_sec>]
Parameters:
- <call_url> URL you are calling.
For more info on sofia sip url syntax see: FreeSwitch Endpoint Sofia - <exten> Extension you are calling from
- <application_name> "&" plus an application name and args.
Here is a list of valid application names that can be used here:
park, bridge, javascript, playback (remove mod_native_file), more ... (Please document) - <cid_name> CallerID name.
- <cid_num> CallerID number.
- <timeout_sec> Timeout in seconds.
Options:
these options can be used in curly braces, example: "originate {ignore_early_media=true}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
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/300@foo.com 8600
Or you could instead connect a remote sip endpoint to another remote extension
originate sofia/example/300@foo.com &bridge(sofia/example/400@bar.com)
Or you could even run a javascript application test.js
originate sofia/example/1000@somewhere.com &javascript(test.js)
To run a javascript with arguments you must surround it in quotes.
originate sofia/example/1000@somewhere.com '&javascript(test.js myArg1 myArg2)'
Setting channel variables before doing the originate
originate {ignore_early_media=true}sofia/mydomain.com/18005551212@1.2.3.4 15555551212
Setting variable to send to another FS box during originate
originate {sip_h_X-varA=111,sip_h_X-varB=222}sofia/mydomain.com/18005551212@1.2.3.4 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/mydomain.com/that.ext@1.2.3.4 15555551212
originate {my_own_var='my value'}sofia/mydomain.com/that.ext@1.2.3.4 15555551212
If you need to fake the ringback to the originated endpoint try this:
originate {ringback=\'%(2000,4000,440.0,480.0)\'}sofia/example/300@foo.com &bridge(sofia/example/400@bar.com)
You can event 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)
pause
Pause <uuid> media
Usage: pause <uuid> <on|off>
read
Read DTMF
Usage: read <min> <max> <sound file> <variable name> <timeout> <terminators>
- min = Minimum number of digits to fetch
- max = Maximum number of digits to fetch
- sound file = Sound file to play before digits are fetched
- variable name = Channel variable that digits should be placed in.
- timeout = Number of milliseconds to wait on each digit
- terminators = digits used to end input if less than <min> digits have been pressed. (Typically '#')
uuid_displace
Displace the audio for the target <uuid> with the specified audio <file>.
Parameters:
- 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]
Examples:
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
uuid_transfer
Transfers an existing call to a specific extension within a <dialplan> and <context>. Dialplan may be "xml" or "directory".
Usage:
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.
uuid_bridge
Bridge two call legs together.
Usage: uuid_bridge <uuid> <other_uuid>
uuid_dump
Dumps all variable values for a session.
Usage: uuid_dump <uuid> [format]
?Format options: XML (any others?)
uuid_park
Park call
Usage: uuid_park <uuid>
Record/Playback Commands
uuid_playback
Plays a file. channel variable "playback_terminators" are used if no terminator digits are used
Usage: playback <uuid> <file_path> <terminator_digits>
- uuid: Channel id
- file_path: FS relative path to sound file
- terminator_digits: DTMF digits that should abort the speech.
record
Records to a file. Can be stopped by pressing *
Usage: record <file_path>
See: Record
record_session
Records an entire phone call or session. The file extension will define the recorded file's format. Use the console command show file to determine possible formats.
Usage: record_session /tmp/test.gsm
See: Record Session
stop_record_session
Stops recording a session.
Usage: stop_record_session <file_path>
uuid_record
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. (TODO: What if media doesn't flow through FS? Will it re-INVITE first? Or do we just not get the audio in that case?)
Usage:
uuid_record <uuid> [start|stop] <path> [<limit>]
where limit is the max number of seconds to record.
Speech Synthesis Commands
IM Commands
chat
Chat with a Jabber/SIMPLE session.
Usage: chat,<proto>|<from>|<to>|<message>,chat
Javascript commands
jsrun
jsrun is used to execute javascripts WITHOUT any active calls. The javascripts can either be started from any of the interfaces, for example from the FreeSWITCH console or from the event socket.
Usage: jsrun <filename> [arguments]
Arguments are used like on a commandline.
Example: jsrun record.js aUserName filename.wav
Arguments are retrieved from the javascripts by using the argv array.
Example (voicemail_out.js):
var caller = argv[0];
var destination = argv[1];
var session = new Session();
session.originate(caller, destination);
session.streamFile("sounds\\you_have.wav");
session.streamFile("sounds\\1.wav");
session.streamFile("sounds\\new_message.wav");
The above script is called with for instance:
jsrun voicemail_out.js sofia/mydomain.com/8334 8888
Misc. Commands
user_exists
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.
Example:
user_exists id 1000 192.168.1.101
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">
<params>
<param name="password" value="1234"/>
<param name="vm-password" value="1000"/>
</params>
<variables>
<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"/>
</variables>
</user>
In the above example, we also could have tested for randomvar:
user_exists randomvar 45 192.168.1.101
and we would have received the same results, but
user_exists accountcode 1000 192.168.1.101
or
user_exists password 1000 192.168.1.101
would have returned false.
find_user_xml
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.
user_data
Retrieves user information (parameters or variables) as defined in the directory.
Usage: user_data <user>@<domain> [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.
Example:
user_data 1000@192.168.1.101 param password
will return a result of 1234, and
user_data 1000@192.168.1.101 var accountcode
will return a result of 1000 from the example user shown in user_exists.
