Page tree
Skip to end of metadata
Go to start of metadata


mod_conference provides both inbound and outbound conference bridge service for FreeSWITCH™. It can process multiple bit rates, load various profiles that specify DTMF controls, play prompt sounds and tones, and many other functions. You can create as many conferences as you like, as long as there still are free system resources (i.e. memory, CPU power, network bandwidth) available.

Conferences created in the dialplan use profiles that are defined in conf/autoload_configs/conference.conf.xml, if you are using the standard configuration files.


 Click to expand Table of Contents

Conference Configuration

Conference configuration settings are stored in conf/autoload_configs/conference.conf.xml

Community member Stanislav Sinyagin has posted a nice personal blog entry on how he configured his conference bridge.

The configuration has the following structure, each "[... config here ...]" should be replaced with specific configuration statements as detailed in the sections that follow.



This block specifies whether empty conferences should be advertised in presence, allowing you to see status of empty conferences. Any endpoint that supports presence, such as mod_sofia, can subscribe to these presence notifications.


Example configuration

The conference name (888 in this case) should be the profile name that you specified in <profiles> section, $${subdomain} will be replaced with the subdomain that you specified in freeswitch.xml.

"status" is advertised as whatever you pass to it (identifier) or "Available" if none is passed.

Example 'advertise' Event via mod_event_multicast


Advertise event


Caller controls are used to modify the state of the conference, such as lowering the volume, mute a participant, and such. Below are the commands that can be assigned to digits and executed during a conference. The "moderator-controls" group provides additional controls for participants who enter the conference with the moderator flag set. See below.

Reserved Control Group Names

noneUse this name to prevent installing caller-controls for callers to a conference.
defaultUse this name to utilize the hard-coded group of controls built into mod_conference. Do NOT name a custom group of conference-controls "default" as they will be overridden with the hard-coded group. 


Each of these actions can be configured in caller-controls to be invoked by a conference member who enters the conference with this caller-controls group. These are instances of the conference API.

ActionDescriptionMin. Version
muteToggle audio from this member into the conference 
mute onDisable audio from this member into the conference 
mute offEnable audio from this member into the conference 
deaf muteBlock audio from conference to this member as well as mute, in one action 
energy upIncrease minimum energy threshold by 1 unit above which sound will be admitted into conference (noise gate) 
energy equReset minimum energy threshold to default 
energy dnDecrease minimum energy threshold by 1 unit 
vol talk upIncrease member talk (mic) volume into conference by 1 unit 
vol talk zeroReset talk volume to default setting 
vol talk dnDecrease talk volume by 1 unit 
vol listen upIncrease member receive (earpiece) volume by 1 unit 
vol listen zeroReset member receive volume to default setting 
vol listen dnDecrease member receive volume by 1 unit 
hangupLeave the conference 
eventSend the DTMF event via CUSTOM conference::maintenance subclass to the event system (even to event socket) 
lockToggle the conference lock state (no new members can enter when locked) 
transferTransfer member to a given extension in a dialplan context 
execute_applicationExecute a dialplan application 
floorToggle yourself on and off of talking floor, as long as no one else has floor status. 
vid-floorVideo floor. If video floor is currently locked, it will revert to auto; if there is no current holder, you become video floor holder1.6
vid-floor-forceVideo floor. If video floor is currently locked, it will revert to auto, otherwise you become the locked video floor holder1.6
vmuteVideo mute. Toggle video from this member into the conference1.6
vmute onDisable video from this member into the conference1.6
vmute offEnable video from this member into the conference1.6
vmute snapTake a video snapshot for this user to be used when in vmute1.6
vmute snapoffDiscard the vmute video snapshot1.6
Default controls
Example Configuration


Be aware that the caller-controls are applied across the entire conference session. You cannot apply one group of caller-controls to one member and then a second group of caller-controls to a second member in the same conference session.



The FreeSWITCH conference also provides limited chat capabilities via SIP, XMPP, and Verto.

A conference can be controlled through chat. This profile exists as part of the conference entity so you can have multiple profiles to limit access. When the conference advertises its presence (above) to a chat server, anyone on a federated server can talk to it and issue commands by typing messages via their favorite chat client (even if that is another FreeSWITCH™ box). To send commands to ConferenceA, from your jabber client send a message to

As of revision 3789 all commands except "list" have been disabled "until there is security"


Another Note: After spending much time trying to get control of mod_conference via Openfire XMPP server, asked around, and "bougyman" suggested that XMPP muc functionality is very limited as of January 2012.

Here is an example configuration

chat-permissions example


You can specify a number of different profiles in the profiles section, these will let you easily apply a number of settings to a conference. Please note that the profiles are not conference rooms, but define settings that are later applied to conference rooms. The dialplan section in this document will describe how you create conference rooms and apply these profile settings.

profiles structure

You can have any number of <profile> tags, and each <profile> can have any number of <param> tags up to the entire set of parameters.

Conference Profile Parameters

You may specify the conference profile parameters listed below. Keep in mind that if TTS is enabled all audio-file params beginning with 'say:' will be considered text to say with TTS. A TTS module must be loaded by FreeSWITCH for this to work.

NameDescriptionExample valueAllowed valueDefault valuePlayed forMin. Version
announce-countRequires TTS. If the number of members equals or exceeds this value, the conference will speak the count to the conference after a new member joins5


auto-gain-levelEnables Automatic Gain Control (AGC). If the parameter is set to 'true', then the default AGC value is used. If set to a number it will override the default value900<integer>|true1100  
auto-recordSet a filename or stream value for this parameter in order to enable recording every conference call. Within mod_conference there is a special parameter named ${conference_name} that can be used to form the record filename. All channel variables are accessible as well for generating a unique filename. NOTE: auto-record doesn't begin recording until the number of conferees specified in min-required-recording-participants have joined.

Example 1: /var/myNFSshare/${conference_name}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav

Example 2: shout://

broadcast-chat-messageMessage to send in response to chat messages.Please go away.<string>   
caller-controlsName of the caller control group to use for this profile. It must be one of those specified in the <caller-controls> sectionsomekeys<control-name>default  
moderator-controlsName of the moderator control group to use for this profile. It must be one of those specified in the <caller-controls> sectionsomekeys<control-name>default  
cdr-log-dirTarget directory for conference CDRs to be written. Use "auto" to store in $PREFIX/log/conference_cdr. An absolute path is acceptable as is a relative path. A relative path will yield $PREFIX/log/<value> for the conference CDR directoryauto<path>|auto   
cdr-event-modeInclude full cdr or path to file in conference cdr eventcontentcontent|file|none   
caller-id-nameDefault Caller ID Name for outbound calls originated by mod_conferenceFreeSWITCH<string>conference  
caller-id-numberDefault Caller ID Number for outbound calls originated by mod_conference8777423583<string>


channelsThe number of audio channels. Special value "auto" sets this based on the channels of the first member to enter11|2|auto1 1.4
comfort-noiseSets the volume level of background white noise to add to the conference. Special value "true" sets to default value. 0 for no CN (total silence).14000-10000|true1400  
conference-flagsCan be any combination of allowed values separated by "|" (pipe character).wait-mod|audio-always

See Table Conference Flags below

descriptionDescription of the conference that is included in some eventsThe main conference<string>   
domainThe domain name used for presence events from conferences$${domain}<string>   
energy-levelNoise gate. Energy level required for audio to be sent to the other users. The energy level is a minimum threshold of 'voice energy' that must be present before audio is bridged into the conference. Useful if a participant is in a noisy environment, so their background noise is heard only when they speak. 0 disables the noise gate and will bridge all packets even if they are only background noise.3000-1800   
intervalNumber of milliseconds per frame. Which may be different from ptime in SIP SDP, or driver with TDM. Higher numbers require less CPU but can degrade conversation quality, so experimentation with your setup is best. The default is good for conversation quality. Special "auto" value sets interval based on interval of the first member who enters.2010-120 (only if divisible by 10) or auto   
max-membersSets a maximum number of participants in conferences with this setting in its profile.20Integer > 1   
member-flagsCan be any combination of allowed values separated by "|". See table below for descriptions.nomoh|muteSee Table Member Flags below   
pinPin code that must be entered before user is allowed to enter the conference.12345<sritng>   
moderator-pinPin code that must be entered before moderator is allowed to enter the conference.12345<string>   
pin-retriesMax number of times the user or moderator will be asked for PIN3

<integer> >= 0

rateAudio sample rate. Special value "auto" sets this based on the rate of the first member to enter.8000

8000, 12000, 16000, 24000, 32000, 44100, 48000, auto

sound-prefixSet a default path here so you can use relative paths in the other sound params./soundfiles<path-string>   
suppress-eventsFor use with the event socket. This parameter is a comma delimited string that specifies which events will NOT be sent to the socket when getting CUSTOM conference::maintenance events.add-member,del-memberSee Table Conference Events below   
terminate-on-silenceSpecifies the number of contiguous seconds of silence after which the conference will automatically terminate and disconnect all members.300<integer> > 0   
timer-nameName of the timer interface in freeswitch to use for timing the conferencesoft<timer-name>soft  
tts-engineText-To-Speech (TTS) Engine to usecepstral<tts-name>   
tts-voiceTTS Voice to usedavid<tts-voice>   
verbose-eventsEvents related to the conference will send more data. Specifically the events related to members will include all the channel variables on each eventtruetrue|falsefalse  
alone-soundFile to play if you are alone in the conferenceyactopitc.wav<sound-path> User 
bad-pin-soundFile to play to when the pin is invalidinvalid-pin.wav<sound-path> User 
enter-soundFile to play when you join the conferencewelcome.wav<sound-path> All 
exit-soundFile to play when you leave the conferenceexit.wav<sound-path> All 
is-locked-soundFile to play when the conference is locked during the call to the members in the conferenceis-locked.wav<sound-path> All 
is-unlocked-soundFile to play when the conference is unlocked during the callis-unlocked.wav<sound-path> All 
join-only-soundFile to play when member with join-only flag tries to create the conference (join as the first).no_reources_try_later.wav<sound-path> User 
kicked-soundFile to play when you are kicked from the conferencekicked.wav<sound-path> User 
locked-soundFile to play when the conference is locked and someone goes to joinlocked.wav<sound-path> All 
max-members-soundIf max-members has been reached, this sound plays instead of allowing new users to the conferencemax-members.wav<sound-path> Caller 
moh-soundthe given sound file/resource will be played only when the conference size is 1 member. It will loop over and over until the member count is 2 or more. When the conference goes back to 1 member it will play againidlemusic.wav<sound-path> All 
muted-soundFile to play when member is mutedmuted.wav<sound-path> User 
mute-detect-soundIf the mute-detect member-flag has been set, this sound plays when the user talks while mutedmute-detect.wav<sound-path> User 
perpetual-soundThe given sound file/resource will be played on a loop forever. This can be used to broadcast sales or emergency messages to callers.announcement.wav<sound-path> All 
pin-soundFile to prompt the user to enter the conference pin<sound-path> User 
unmuted-soundFile to play when member is unmuted.unmuted.wav<sound-path> User 
ivr-dtmf-timeoutInter-digit timeout between DTMF digits in milliseconds500

<integer> >= 500

ivr-input-timeoutTime to wait for the first DTMF in milliseconds, zero = forever0<integer> >= 5000 or 00  
endconf-grace-timeDefines how much time all members have before the conference is terminated when the last member with endconf leaves in seconds600<integer> >= 00  
min-required-recording-participantsMinimum number of conference participants required for their audio to be heard in a recording and for auto recording to start. This can be either 1 (the default) or 2.11-21  
outcall-templTemplate to use for outcall URL <string>   
video-modeThe mode to run video conferencing in. passthrough is non transcoded video follow audio. transcode allows for better switching and multiple codecs. mux allows for multiple parties on the video canvas at the same time





 passthrough 1.6
video-layout-nameThe layout name from conference_layouts.conf.xml or group prefixed by "group:". Setting this setting will enable the video mux. Not setting this will switch video presentation based on floor.



<layout-name> or group:<group-name>  1.6
video-canvas-bgcolor Overall Canvas color for video mux canvas as an HTML HEX color code #333333 <color-spec>




Color to use for bars on the caller video if their aspect ratio doesn’t fit the member square in the layout as an HTML HEX color code #FFFFFF <color-spec>


video-canvas-sizePixel dimensions of the video mux canvas800x600<integer>x<integer>  1.6
video-fpsFrames per second to run the video mux at15<integer>15 1.6

The bandwidth maximum for the conference output video stream, This setting can be auto, our defined in KB (kilobytes), mb (megabits) or MB (megabytes)

1MBauto|<integer>KB|<integer>mb|<integer>MB  1.6
video-no-video-avatarPath to PNG file for member without video to display.    1.6
video-canvas-countNumber of canvases to use in mux mode11-51 1.6
Table: Member Flags

These flags can be applied to individual conferees when entering the conference to control what they can do and how their media is processed.

Member FlagDescriptionMin. Version
muteEnter conference muted 
deafEnter conference deafed (can not hear conference); will also mute the mic 
mute-detectPlay the mute_detect_sound when talking detected by this conferee while muted 
dist-dtmfSend any DTMF from this member to all participants 
moderatorFlag member as a moderator 
nomohDisable music on hold when this member is the only member in the conference 
endconfEnds conference when all members with this flag leave the conference after profile param endconf-grace-time has expired 
mintwoEnd conference when it drops below 2 participants after a member enters with this flag 
ghostDo not count member in conference tally 
join-onlyOnly allow joining a conference that already exists 
positionalProcess this member for positional audio on stereo outputs1.4
no-positionalDo not process this member for positional audio on stereo outputs1.4
join-vid-floorLocks member as the video floor holder1.6
no-minimize-encodingBypass the video transcode minimizer and encode the video individually for this member1.6
vmuteEnter conference video muted1.6
second-screenOpen a 'view only' connection to the conference, without impacting the conference count or data.1.6
Table: Conference Flags

These flags control the operation of the conference session and apply to all members.

Conference FlagDescriptionMin. Version
wait-mod Members will wait (with music) until a member with the 'moderator' flag set enters the conference1.0
audio-alwaysDo not use energy detection to choose which participants to mix; instead always mix audio from all members1.2


rfc-4579Enable support for RFC-4579 SIP–based call control for conferences1.4
livearray-syncAdd support for livearray advertisement for the conference status1.4
auto-3d-positionEnable 3d positioned audio support1.4
json-eventsSend event-channel JSON events when members enter and leave1.4
video-floor-onlyOnly video members can get floor. REMOVED in 1.61.4

Use a single video encoder per output codec



Machine parseable version of display for conference live array. Example:



video-bridge-first-twoIn mux mode, If there are only 2 people in conference, you will see only the other member1.6
video-muxing-personal-canvasIn mux mode, each member will get their own canvas and they will not see themselves1.6
video-required-for-canvasOnly video participants will be shown on the canvas (no avatars)1.6
Table: Conference Events

These events are available to event consumers.

Event NameDescription
add-memberMember added to a conference


Member removed from a conference
energy-levelConference default energy level changed
volume-levelConference default volume level changed
gain-levelConference default gain level changed
dtmfKey bound to transfer, event, or execute_application is hit by member
stop-talkingMember stopped talking (as detected by energy level)
start-talkingMember started talking (as detected by energy level)
mute-detectDetected member speaking (as detected by energy level) while muted
mute-memberMember became muted
unmute-memberMember became unmuted
kick-memberMember kicked
dtmf-memberKey bound to DTMF is hit by member
energy-level-memberMember energy level changed
volume-in-memberMember gain level changed
volume-out-memberMember volume level changed
play-fileConference–level play file started
play-file-doneConference–level play file ended
play-file-memberMember–level play file started
lockConference locked, no one else can enter
unlockConference unlocked
transferMember transferred to another conference
bgdial-resultResult from bgdial API command
floor-changeConference floor changed
recordConference recording started or stopped


Conference Dialplan Application

The conference dialplan application is used to create conferences and to bind a profile to them.


The first time a conference name (confname) is used, it will be created on demand, and the pin will be set to what ever is specified at that time: the pin in the data string if specified, or if not, the "pin" setting in the conference profile, and if that is also unspecified, then there is no pin protection. Any later attempt to join the conference must specify the same pin number, if one existed when it was created.

"profile" should be one of those specified in the conference configuration, or "default".

If the data value starts with "bridge:" then it is a bridging conference. The conference name should not be already in use. You can specify the special literal value of "_uuid_" for the conference name, and a a session-specific unique id will be generated for you.

Conferences stay alive until the number of members falls below the minimum. The minimum for bridging conferences is 2, and for other dynamically created conferences is 1.

Dialplan Examples

Action dataDescription
confnameprofile is "default", no flags or pin
confname+1234profile is "default", pin is 1234
confname@profilename+1234profile is "profilename", pin=1234, no flags
confname+1234+flags{mute}profile is "default", pin=1234, one flag
confname++flags{endconf|moderator}profile is "default", no p.i.n., multiple flags
bridge:confnamea "bridging" conference
bridge:_uuid_a "bridging" conference with UUID assigned as conference name
*Note that while some parameters are optional, their order is very important
Simple Dialplan Example
Bridging conference example that plays ringback while other party is bridged in

Adding Callers From Within The Conference With DTMF

By combining several elements — the dialplan, API calls, bind_digit_action — you can create a simple system for a caller to add another user to the conference. See Conference_Add_Call_Example for the code and explanation.

Announcing Caller Count While In Conference

See Conference Announce Count Inline for a simple example of how to allow a caller to hear an announcement of how many members are in the conference.

Propagate Out-of-Band DTMF to Conference Members

By default, out-of-band DTMF signals (RFC 2833?) are absorbed by the conference. However, there are two ways to accomplish this:

  • Set the dist-dtmf member flag in the conference configuration XML, eg: <param name="member-flags" value="dist-dtmf"/> With this parameter set, all of the caller controls such as modifying volume will be disabled and DTMF will simply pass through to all other members of the conference.
  • There is also an API call that will allow your application to send DTMF to a single conference member or all members:
    <confname> dtmf-string <[member_id|all|last]> <digits>

Prompt for Name

Dialplan to prompt callers to speak their names before joining the conference and announce their name to other participants.

Speak name


API Reference

CommandDescriptionSyntaxExamplesMin. Version
agcAdjust conference automatic gain control.conference <confname> agc [on [<level>] | off]
Query level: conference testconf agc
Disable: conference testconf agc off
Enable: conference testconf agc on
Enable w/ level: conference testconf agc on 1120
bgdialBackground dial a destination via a specific endpoint conference <confname> bgdial <dial-string> [<callerid_number> [<callerid_name>]]  
chkrecordQuery record status of conferenceconference <confname> chkrecord  
deafMake a conference member deafconference <confname> deaf <member_id>|all|last|non_moderator  
dialDial a destinationconference <confname> dial <dial-string> [<callerid_number> [<callerid_name>]]  
dtmf Send DTMF to any member of the conferenceconference <confname> dtmf <member_id>|all|last|non_moderator <digits> conference testconf dtmf all 134 
energyAdjusts the conference energy level for a specific member conference <confname> energy <member_id>|all|last|non_moderator <newval>  
enter_soundChanges the sound played while entering the conferenceconference <confname> enter_sound on|off|none|file <filename>    
exit_soundChanges the sound played while leaving the conferenceconference <confname> exit_sound on|off|none|file <filename>    
floorToggle floor status of the member.conference <confname> <member_id>|all|last|non_moderator   
file_seekSeek to a point in the currently playing file, in millisecondsconference <confname> file_seek [+|-]<val>

Move forward 1 second: conference testconf file_seek +1000

Move backwards 1 second: conference testconf file_seek -1000

Move to 10 seconds from the start: conference testconf file_seek 10000

file-volChanges the volume of the currently playing sound fileconference <confname> file-vol <val> [async]  

Get runtime parameter of the given conference

(table of allowed parameters below)

conference <confname> get <parameter_name>  
hupKick without the kick soundconference <confname> hup <member_id>|all|last|non_moderator   
kickKicks the member or all members from the conferenceconference <confname> kick <member_id>|all|last|non_moderator   
listLists conferencesconference list [pretty|summary|count|delim <string>]  
lockLock a conference so no new members will be allowed to enterconference <confname> lock  
muteMutes a conference memberconference <confname> mute <member_id>|all|last|non_moderator [quiet]  
nopinRemoves a pin from a conferenceconference <confname> nopin  
norecordRemoves a recording or all recordings from a conferenceconference <confname> norecord <file-path>|all

conference testconf norecord all

conference testconf norecord /tmp/foo.wav

pausePause a conference recordingconference <confname> pause <file-path>  
pause_playPause playback of file to a conferenceconference <confname> pause_play  
pinSet or change a pin number for a conferenceconference <confname> pin <pin-number>

Note: Members joined from conference dial command

do not get prompted for a pin

playPlay an audio file to a conference or a specific memberconference <confname> play [{vol=<volume>,full-screen=true,png_ms=100}]<file-path> [async|<member_id> [nomux]]full-screen param will play the video in full screen mode in the conference,
png_ms depends on mod_png to be loaded, Specify a PNG file to play and how many milliseconds, -1 for indefinite
recordRecord a conference to a file or streamconference <confname> record <file-path>


recordingStart or control a conference recording

conference <confname> recording start <file-path>

conference <confname> recording check

conference <confname> recording stop <file-path>|all

conference <confname> recording pause <file-path>

conference <confname> recording resume <file-path>


Mute or Deaf a specific member to another member

Control who sees who's video when not using video mux

conference <confname> relate <member_id> <other_member_id> [nospeak|nohear|clear|sendvideo]

resumeResume recordingconference <confname> resume <file-path>  
saySpeak text into conference using TTSconference <confname> say <text>  
saymemberSpeak text to a member of a conference using TTSconference <confname> saymember <member_id> <text>  
setSet runtime parameter of a conferenceconference <confname> set <parameter_name> <value>  
stopStops any queued audio from playing into conferenceconference <confname> [current|all] [<member_id>]  
tmuteToggle mute on/off for a member of a conferenceconference <confname> tmute <member_id>|all|last|non_moderator [quiet]  
transferTransfer a member from one conference to another conferenceconference <confname> transfer <conference_name> <member_id>  
undeafAllow conference member to hear againconference <confname> undeaf <member_id>|all|last|non_moderator  
unlockUnlock a conference so that new members can enterconference <confname> unlock  
unmuteUnmute a conference memberconference <confname> unmute <member_id>|all|last|non_moderator [quiet]  
volume_inAdjust the gain on the audio coming from a memberconference <confname> volume_in <member_id>|all|last|non_moderator [<newval>]  
volume_outAdjust the volume of audio going to a memberconference <confname> volume_out <member_id>|all|last|non_moderator [<newval>]  
xml_listList all or specific conferences in XML format

conference xml_list

conference <confname> xml_list

vid-floor Set or force the video floor for a memberconference <confname> vid-floor <member_id>|last [force] 1.6
vmute Enable video mute for a memberconference <confname> vmute <member_id>|all|last|non_moderator [quiet] 1.6
tvmute Toggle video mute on/off for a memberconference <confname> tvmute <member_id>|all|last|non_moderator [quiet] 1.6
vmute-snap Take or clear a snapshot image of the member to be used during vmuteconference <confname> vmute-snap <member_id>|all|last|non_moderator [clear] 1.6
unvmute Unmute video for a memberconference <confname> unvmute <member_id>|all|last|non_moderator [quiet] 1.6
vid-banner Set a text banner on the members videoconference <confname> vid-banner <member_id>|all|last|non_moderator <text> 1.6
vid-mute-img Check, set or clear the file to use as the members video mute imageconference <confname> vid-mute-img <member_id>|all|last|non_moderator [<path>|clear] 1.6
vid-logo-img Check, set or clear the file to use as the members video logo imageconference <confname> vid-logo-img <member_id>|all|last|non_moderator [<path>|clear] 1.6
vid-res-id Set or clear the video reservation id for this memberconference <confname> vid-res-id <member_id>|all|last|non_moderator <val>|clear 1.6
clear-vid-floor Clear when the video floor is locked to a userconference <confname> clear-vid-floor 1.6
vid-layout List available video mux layouts or set the layout or group to use in the video muxconference <confname> vid-layout list|<layout-name>|group <group_name> [<canvas_id>] 1.6
vid-fpsSet the frames per second rate of the video mux output for the conferenceconference <confname> vid-fps <fps> 1.6
vid-bandwidthSet the bandwidth used by the output video from the conferenceconference <confname> vid-bandwidth <BW> 1.6
vid-write-pngTake a snapshot of the current video mux output and save it to a PNG fileconference <confname> vid-write-png <path> 1.6
vid-canvasSet the canvas to display this member onconference <confname> vid-canvas  <member_id>|all|last|non_moderator [<canvas_id>] 1.6
vid-watching-canvasSet the canvas displayed to this memberconference <confname> vid-watching-canvas  <member_id>|all|last|non_moderator [<canvas_id>] 1.6

API Additional Notes

dial and bgdial

If the caller id values are not set, the variables in conference.conf.xml will be used. Specifically, the value for caller-id-number will be used for the number and the value for caller-id-name will be used for the name.

If the conference will be dynamically created as a result of this api call (ie this will be the first participant in the conference) - and the caller id name and number is not provided in the api call - the number and name will be "00000000" and "FreeSWITCH". This appears to be unaffected by the variables in conference.conf.xml.

get and set

run_time Seconds 
count Number 
max_members NumberYes
rate Number 
profile_name String 
sound_prefix StringYes
caller_id_name StringYes
caller_id_number StringYes
is_locked "locked" or blank 
endconf_grace_time SecondsYes
uuid String 
wait_mod "true" or blank 
Dialplan usage example


Command Output

First line:

  • Conference <conference name> (<member_count> member[s][ locked])
    • “locked” - The lock/unlock status of the conference.

Each following line is a comma-separated list for each conference leg with the following items:

  • id of participant(starts at 1 after FS restart)
  • Register string of participant
  • UUID of participant's call leg
  • Caller id name
  • Caller id number
  • Status (hear|speak|talking|video|floor)
    • “hear” - The mute/unmute status of the member.
    • “speak” - The “deaf /undeaf” status of the member.
    • “talking” - The input channel is currently providing some amount of sound energy into conference.
    • “video” - Providing video?
    • “floor” - This member currently owns the floor.
  • Volume In setting
  • Detected energy
  • Volume Out setting
  • Energy Level setting


A handy way to test in an XML dialplan if a conference is active and allow a late caller to join

If the conference is not active, the second "condition" test will fail and bypass this dialplan extension entry. If the conference is active the caller will join it with the 'nomoh' flag set.



conference my_conf relate 1 2 nospeak

Member 1 may now no longer speak to member 2, i.e. member 2 now cannot hear member 1.

conference my_conf relate 1 2 clear

Member 1 may now speak to member 2 again


conference my_conf relate 1 2 nohear

Member 1 now cannot hear member 2

conference my_conf relate 1 2 clear

Member 1 can now hear member 2 again

Event Socket Use

You can subscribe to the following to receive conference events:


The "suppress-events" parameter can be added to the conference profile to prevent events from firing. e.g. if you're not interested in start or stop talking events:

  <profile name="default">
    ...other options...
    <param name="suppress-events" value="start-talking,stop-talking"/>

The events that can be suppressed are:

add-member, del-member, energy-level, volume-level, gain-level, dtmf, stop-talking, start-talking, mute-member, unmute-member, kick-member, dtmf-member, energy-level-member, volume-in-member, volume-out-member, play-file, play-file-member, speak-text, speak-text-member, lock, unlock, transfer, bgdial-result and floor-change.

Outbound Conference

Use conference_set_auto_outcall to have mod_conference call endpoints and join them to a conference bridge. To have it call more than one participant, just repeat the conference_set_auto_outcall action in the dialplan for each destination number or address.



Here is an example of using conference_set_auto_outcall with some of the other conference_auto_outcall_* parameters to start a conference when someone dials 12345. Extensions 1000 and 1001 will be dialed when the conference starts and will enter the conference muted.

Outbound example

Alternatively, you can set multiple destinations in one line, just remember to escape your variables if you have more than one or any non-escaped chars in it.

conference_auto_outcall_announceFile name of audio message to play to conference member joining conference via the conference_set_auto_outcall application.
conference_auto_outcall_caller_id_nameCaller ID name to use when dialing endpoints using conference_set_auto_outcall application
conference_auto_outcall_caller_id_numberCaller ID number to use when dialing endpoints using conference_set_auto_outcall application
conference_auto_outcall_flagsConference member flags to set for members joining via conference_set_auto_outcall application
conference_auto_outcall_maxwaitMaximum time in seconds that the channel that initiated the conference_set_auto_outcall will wait for members to join the conference
conference_auto_outcall_prefixString to prepend to each of the dial-string values set from the conference_auto_outcall application
conference_auto_outcall_profileConference profile to use for members joining the conference via the conference_set_auto_outcall application
conference_auto_outcall_timeoutOriginate timeout to use when joining a member to a conference via conference_set_auto_outcall application


Channel Variables


These channel variables are set by mod_conference.

conference_last_matching_digitsContains the last matching digits that the member sent into the conference
conference_member_idContains the member_id of the member for the conference they are in
conference_moderatorContains "true" if the channel is connected to a conference as a moderator
conference_nameThe name of the last conference joined by this channel
conference_recordingContains the file name of the conference recording for the conference the channel is connected to
conference_uuidUnique id of the most recent conference in which the channel was a member
last_transferred_conferenceThe name of the last conference this channel was connected to


Settable Channel Variables

Set these channel variables to control the behavior of mod_conference for the current session.  conference_auto_outcall_ variables are described above in the Outbound Conference section

VariableDescriptionExampleMin. Version
conference_controlsSpecify which conference control set to use when transferring a caller into a conference
<action application="set" data="conference_controls=moderator"/>

Allows the conference security to be overridden. This applies in two different scenarios, one for inbound and one for outbound.

By default, conference security is always applied to inbound calls and is always skipped for outbound calls.


<action application="set" data="conference_enforce_security=false"/>
<action application="conference" data="3000"/>


originate {conference_enforce_security=true}sofia/internal/1001 &conference(3000)
conference_enter_soundOverrides the conference parameter for enter sound
<action application="set" data="conference_enter_sound=silence_stream://10"/>
conference_exit_soundOverrides the conference parameter for exit sound
<action application="set" data="conference_exit_sound=silence_stream://10"/> 
conference_flagsA comma separated list of conference flags, which will be applied when the conference is created. This allows to dynamically set the conference flags from the dial plan as opposed to setting them in the conference profile.
<action application="set" data="conference_flags=wait-mod,audio-always"/>
conference_member_flagsA comma separated list of member flags to be set on the channel, which is joining the conference.
<action application="set" data="conference_member_flags=mute"/>

This variable controls how the enter and exit sounds interact with the MOH when the wait_mod flag is set. When this variable is set to true, the MOH keeps playing and
the enter and exit sounds are mixed with the MOH. When the variable is false or not set, then any playing MOH is first stopped, then the enter or exit sound is played and the MOH is started again.

This functionality is useful in case the enter and exit sounds are used to announce the name of the caller, who is joining or leaving a conference.



video_banner_textSets the video banner text, font, font size, font color, and background color for the member (must be set before entering conference). font_scale valid values 5-50, fg/bg hex color code, all settings besides text are optional.<action application="set" data="video_banner_text={font_face=/path/to/font.ttf,font_scale=5,bg=#000000,fg=#FFFFFF}Banner Text"/>1.6
video_mute_png Path to PNG file to use when you video mute, by default it will use your last video frame. <action application="set" data="video_mute_png=/path/to/file.png"/>1.6
video_no_video_avatar_pngPath to PNG file for member without video to display.<action application="set" data="video_no_video_avatar_png=/path/to/file.png"/>1.6

set video replacement avatar images

<action application="set" data="video_avatar_png=/path/to/file.png"/>1.6
video_initial_canvasSet to the initial canvas member should be displayed on<action application="set" data="video_initial_canvas=2"/>1.6
video_initial_watching_canvasSet to the initial canvas member should see<action application="set" data="video_initial_watching_canvas=2"/>


video_use_dedicated_encoderIf set to true, it allows the channel to have a dedicated encoder with its own bandwidth settings<action application="set" data="video_use_dedicated_encoder=true"/>1.6
conference_auto_recordEnable recording for this conference.<action application="set" data="conference_auto_record=/tmp/${strftime(%Y-%m-%d %H:%M)}.wav"/>1.6


Sound files

Just about any format is supported, but currently it must be at the sample rate of the conference (no resampling is done). Since disk is cheaper than CPU, use a wav.

Custom Conference Layouts

Layout grid is square, its directly proportional to the canvas resolution and aspect ratio.  These layouts will work on 4:3 or 16:9 aspect ratio.  The values x, y, and scale are all of a range of 0-360, proportional to the actual final resolution.

Layout Example
Layout Image ParamDescription
xValue from 0-360, proportional to the canvas size, amount out of 360 for this images top left corner x position
yValue from 0-360, proportional to the canvas size amount out of 360 for this images top left corner y position
scaleValue from 0-360, proportional to the canvas size amount out of 360 for this images size
floorwith floor="true", this box will prefer the video floor holder and will switch as floor holder changes
reservation_idarbitrary named setting used to specify which location to put someone using the vid-res-id api command
overlapwith overlap="true", this box will be redrawn on every frame. You must set this if box overlaps others to avoid flicker
floor-onlywith floor-only="true" this box will only show the video floor holder, and will be blank if there is none


with file-only="true" this box will only show video files that are played via the conference play api.

Uses OpenAL to position the audio into the location of the square the speaker is in.

Values are x:y:z where x, y and z are values on 3d coordinate system.  These can be positive or negative floating point numbers.

The larger the number, the further the “distance”.  X=left/right, Y=forward/backard, X=up/down.  These are the same values used in the conference position command.


Automatically position the conference member based on their location in the current layout.

Check this page for layout examples: FreeSWITCH 1.6 Video#Examples

See Also

Conference Add Call Example