Mod conference

From FreeSWITCH Wiki
Jump to: navigation, search
Warning

Superseded by Confluence

 


Contents

General

The mod_conference module provides multi-user conference features. You can create as many conferences as you like, as long as there still are free system resources (i.e. memory, CPU power) left.

Conferences are created according to configuration within the dialplan.

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

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

Conference configuration

The configuration has the following structure, each "[... config here ...]" should be replaced with a configuration.

<configuration name="conference.conf" description="Audio Conference">
  <advertise>
    	[... config here ...]
  </advertise>

  <caller-controls>
    <group name="default">
    	[... config here ...]
    </group>
  </caller-controls>

  <profiles>
    <profile name="default">
    	[... config here ...]
    </profile>
  </profiles>

  <chat-permissions>
    <profile name="default>
    	[... config here ...]
    </profile>
  </chat-permissions>    
</configuration>

<advertise>

Specifies whether changes in the conference (as leaving and entering) should be advertised... The following information will be advertised to a Jabber/XMPP server.

(someone please complete this list)

  • Enter - Someone entered the conference.
  • Leave - someone left the conference.
  • Mute - Someone muted/unmuted the conference.

Example configuration

  <advertise>
    <room name="888@$${subdomain}" status="FreeSWITCH"/>
  </advertise>

The 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

proto: conf
login: 888@example.com
from: 888@example.com
status: FreeSWITCH
rpid: idle
event_type: presence
Event-Name: PRESENCE_IN
Core-UUID: c76e2d7d-39d7-dc11-93bf-0090fb0792c6
FreeSWITCH-Hostname: example.com
FreeSWITCH-IPv4: 192.168.1.5
FreeSWITCH-IPv6: 127.0.0.1
Event-Date-Local: 2008-02-09 13:04:44
Event-Date-GMT: Sat, 09 Feb 2008 18:04:44 GMT
Event-Date-timestamp: 1202580284348009
Event-Calling-File: mod_conference.c
Event-Calling-Function: send_presence
Event-Calling-Line-Number: 5037
Multicast-Sender: example.com

<caller-controls>

Caller controls are used to modify the state of the conference. It can be lowering the volume, mute the conference and such. Below are the possible commands that can be assigned to digits and executed during a conference... NOTE: As of Oct 3 2011 (1936c2b) , there is a new "moderator-controls" parameter. See below.

Actions

  • mute - Toggle audio from this member into the conference.
  • deaf mute - Block audio from conference to this member as well as mute, in one action
  • energy up - Increase minimum energy threshold above which sound will be admitted into conference
  • energy equ - Reset minimum energy threshold to default
  • energy dn - Decrease minimum energy threshold by 1 unit
  • vol talk up - Increase member talk volume into conference by 1 unit
  • vol talk zero - Reset talk volume to default setting
  • vol talk dn - Decrease talk volume by 1 unit
  • vol listen up - Increase member receive volume by 1 unit
  • vol listen zero - Reset member receive volume to default setting
  • vol listen dn - Decrease member receive volume by 1 unit
  • hangup - Leave the conference
  • lock - Toggle the conference lock state (no new members can enter when locked)
  • event - Send the DTMF event via CUSTOM conference::maintenance subclass to the event system (even to event socket)
  • transfer - Transfer caller to a given extension dialplan context
  • execute_application - Execute a dialplan application


Reserved Group Names

  • none - Use this name to prevent installing caller-controls for callers to a conference.
  • default - Use this name to utilize the hard-coded set of controls built-in to mod_conference. Do NOT name a custom set of conference-controls "default" as they will be overridden with the hard-coded set. The behavior of the "default" group is defined below:
   <group name="default">
      <control action="vol talk dn"      digits="1"/>
      <control action="vol talk zero"    digits="2"/>
      <control action="vol talk up"      digits="3"/>
      <control action="vol listen dn"    digits="4"/>
      <control action="vol listen zero"  digits="5"/>
      <control action="vol listen up"    digits="6"/>
      <control action="energy dn"        digits="7"/>
      <control action="energy equ"       digits="8"/>
      <control action="energy up"        digits="9"/>
      <control action="mute"             digits="0"/>
      <control action="deaf mute"        digits="*"/>
      <control action="hangup"           digits="#"/>
   </group>


Example Configuration

  <caller-controls>
    <group name="somekeys">
      <control action="vol talk dn"         digits="1"/>
      <control action="vol talk zero"       digits="2"/>
      <control action="vol talk up"         digits="3"/>
      <control action="transfer"            digits="5"   data="100 XML default"/>
      <control action="execute_application" digits="0"   data="playback conf_help.wav"/>
      <control action="execute_application" digits="#"   data="execute_dialplan conference-menu"/>
    </group>
  </caller-controls>

Limitations

Be aware that the caller-controls are applied across the entire conference. You cannot enter one member of the conference using caller-controls ABC and then enter a second member using caller-controls XYZ.

<chat-permissions>

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

Note: 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 at present (January 2012). So watch this space.

Here is an example configuration

 <configuration name="conference.conf" description="Audio Conference">
  <profiles>
   <profile name="default">
    <param name="chat-permissions" value="default"/>
   </profile>
  </profiles>
  <chat-permissions>
   <profile name="default">
    <!-- both of these users have a functionally equivalent capability set -->
    <user name="bob@somewhere.com" commands="all"/>
    <!-- individually specified commands must be book-end'ed with the | character -->
    <user name="harry@somewhere.com" commands="|deaf|dial|energy|kick|list|lock|mute|norecord|play|record|relate|say|saymember|stop|transfer|undeaf|unlock|unmute|volume_in|volume_out|"/>
   </profile>
  </chat-permissions>
 </configuration>

<profiles>

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

The profiles section has this structure:

  <profiles>
    <profile name="default">
      <param name="paramName" value="paramValue"/>
    </profile>
  </profiles>

You can have any number of <profile> tags, and each <profile> can have any number of <param> tags (as long as there are parameters to configure ;-) ).

Conference Parameters

You may specify the 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.

Name Description Example value Played for
announce-count Requires TTS. If the number of members equals or exceeds this value, the conference will speak the count after a new member joins. 5
auto-gain-level Enables 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 value. 1100
auto-record Put a value in for this parameter in order to toggle recording every conference call. Within mod_conference there is a special parameter named ${conference_name}. All channel variables are accessible as well. NOTE: auto-record doesn't begin recording until two parties are on the line. Example 1: /var/myNFSshare/${conference_name}_${strftime(%Y-%m-%d-%H-%M-%S)}.wav Example 2: shout://user:pass@server.com/live.mp3
caller-controls Name of the caller control group to use for this profile. One of those specified in the <caller-controls> section. The profile named "default" will be used if none is specified. somekeys
moderator-controls Name of the moderator control group to use for this profile. One of those specified in the <caller-controls> section. The profile named "default" will be used if none is specified. somekeys
cdr-log-dir Target 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 directory. auto
caller-id-name Default Caller ID Name for outbound calls originated by mod_conference. FreeSWITCH
caller-id-number Default Caller ID Number for outbound calls originated by mod_conference. 8777423583
comfort-noise Sets the volume level of background white noise to add to the conference. 1-10000, "true" (defaults to 1400), 0 for no CN (total silence)
conference-flags Can be any combination of wait-mod, audio-always, video-bridge, video-floor-only and rfc-4579. wait-mod is used to force conference participants to wait (with music) for a member with the 'moderator' flag set to enter the conference. The moderator member-flag is set in the dialplan where the call is sent to the conference. This might be used in conjunction with an IVR where the moderators are authenticated with an extra pass-code. The flag audio-always will always mix audios of all members. By default it only mix audios of members who are considered "talking". wait-mod
domain  ??? $${domain}
energy-level Energy level required for audio to be sent to the other users. The energy level is a 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 you only hear background noise when they speak. 0 disables the detection and will bridge all packets even if they are only background noise. 300
interval Number 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. 20
max-members Sets a maximum number of participants in conferences with this setting in its profile. 20
member-flags Can be any combination of: mute, deaf, mute-detect, dist-dtmf, moderator, nomoh, endconf, mintwo, video-bridge, ghost and join-only. mute joins the member to the conference muted (unable to speak into the conference bridge). deaf blocks audio from the conference to the member and implies mute as well; caller-controls can be used to toggle these settings after joining the conference. dist-dtmf passes DTMF TouchTone™ audio to the conference instead of intercepting it as a command. moderator gives greater control over the conference and should not be set within the XML profile, but rather from the dialplan. nomoh disables music-on-hold; this is recommended as m.o.h. would disrupt the conference. endconf terminates a conference when a member with this flag leaves; if more than one member has the endconf flag set, the conference will be terminated when the last endconf member leaves. mintwo terminates the conference if only one participant exists.

The ghost user is not counted as a conference member. With join-only a user cannot create a conference (as a first member), one can only join the conference which is already ongoing.

nomoh
pin Pin code that must be entered before user is allowed to enter the conference. 12345
moderator-pin Pin code that must be entered before moderator is allowed to enter the conference. 12345
pin-retries Max number of times the user or moderator can be asked for PIN 3
rate Audio sample rate. 8000
sound-prefix Set a default path here so you can use relative paths in the other sound params. /soundfiles
suppress-events For use with the event socket. This parameter specifies which events will NOT be sent to the socket when getting CUSTOM conference::maintenance events. add-member
terminate-on-silence Specifies the number of contiguous seconds of silence after which the conference will automatically terminate and disconnect all members. 300
timer-name  ???  ???
tts-engine Text-To-Speech (TTS) Engine to use cepstral
tts-voice TTS Voice to use david
verbose-events Maximum verbosity for transcripting. Events related to the conference will send more data. Specifically the events will include all the channel variables on each conference event. true
ack-sound File to play to acknowledge success. beep.wav User
alone-sound File to play if you are alone in the conference yactopitc.wav User
bad-pin-sound File to play to when the pin is invalid invalid-pin.wav User
enter-sound File to play when you join the conference. welcome.wav All
exit-sound File to play when you leave the conference. exit.wav All
is-locked-sound File to play when the conference is locked during the call to the members in the conference. is-locked.wav All
is-unlocked-sound File to play when the conference is unlocked during the call is-unlocked.wav All
kicked-sound File to play when you are kicked from the conference. kicked.wav User
locked-sound File to play when the conference is locked and someone goes to join locked.wav All
max-members-sound If max-members has been reached, this sound plays instead of allowing new users to the conference. max-members.wav  ???
moh-sound the 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 again. idlemusic.wav All
muted-sound File to play when member is muted. muted.wav User
mute-detect-sound If the mute-detect member-flag has been set, this sound plays when the user talks while muted. mute-detect.wav User
nack-sound File to play to acknowledge failure.

??? What is it acknowledging ???

beeperr.wav User
perpetual-sound The 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 All
pin-sound File to prompt the user to enter the conference pin code. pin.wav User
unmuted-sound File to play when member is unmuted. unmuted.wav User
join-only-sound File to play when member with join-only flag tries to create the conference (join as the first). no_reources_try_later.wav User
ivr-dtmf-timeout milliseconds. Inter-digit timeout between DTMF digits that form a command sequence. 500
ivr-input-timeout How many ms to wait for the first DTMF, zero = forever 0
endconf-grace-time Defines how much time all members have before the conference is terminated when the last member with endconf leaves. Default = 0. 600
min-required-recording-participants Minimum number of conference participants required for their audio to be heard in a recording and for auto recording to start. This can be either 2 (the default) or 1. 2



Conference Dialplan Application

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

Syntax

<action application="conference" data="[bridge:]confname[@profile][+[pin][+flags{mute|deaf|...}]]">

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 that you specified in the conference configuration.

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 reaches the minimum number, and then falls below that. The minimum for bridging conferences is 2, and for other dynamically created conferences is 1.

Examples

Action data Description
confname profile is "default", no flags or pin
confname+1234 profile is "default", pin is 1234
confname@profilename+1234 profile 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:confname a "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

Or a simple example in an action tag:

<action application="conference" data="meeting@mykeys">

Bridging conference example that plays ringback while other party is bridged in:

<extension name="test_bridging_conference">
   <condition field="destination_number" expression="^(3000)$">
      <action application="answer"/>
      <action application="playback" data="connecting_your_call.wav"/>
      <action application="set" data="ringback=${us-ring}"/>
      <action application="conference" data="bridge:$1-${domain_name}@default:user/1000@${domain_name}"/>
   </condition>
</extension>
Adding Callers To The Conference With DTMFs

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


Dialplan to Have Callers Speak Their Names Before Joining the Conference and Announce Name to Other Participants
  <extension name="Record Name and schedule conf announce">                                                                                                     
   <condition field="destination_number" expression="^55(3\d\d\d)$">                                                                                           
     <action application="answer"/>                                                                                                                            
     <action application="set" data="namefile=/tmp/${uuid}-name.wav" inline="true"/>                                                                           
     <action application="sleep" data="1000"/>>                                                                                                                
     <action application="playback" data="voicemail/vm-record_name1.wav"/>                                                                                     
     <action application="playback" data="tone_stream://%(1000,0,500)"/>                                                                                       
     <action application="record" data="${namefile} 1"/>                                                                                                       
     <action application="playback" data="ivr/ivr-call_being_transferred.wav"/>                                                                                
     <action application="set" data="res=${sched_api +1 none conference $1-${domain} play file_string://${namefile}!conference/conf-has_joined.wav}"/>         
     <action application="transfer" data="$1 XML default"/>                                                                                                    
   </condition>                                                                                                                                                
 </extension>


Conference_set_auto_outcall Dialplan Application

Use conference_set_auto_outcall to have mod_conference call one or more endpoints when a conference starts. To have it call more than one endpoint, just repeat the conference_set_auto_outcall action in the dialplan.

Syntax

<action application="conference_set_auto_outcall" data="dialstring"/>

Example

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.

   <extension name="Demonstrate conference_set_auto_outcall">
     <condition field="destination_number" expression="^(12345)$">
       
       <action application="answer"/>
       
       <action application="set" data="conference_auto_outcall_timeout=5"/>
       <action application="set" data="conference_auto_outcall_flags=none"/>
       <action application="set" data="conference_auto_outcall_caller_id_name=$${effective_caller_id_name}"/>
       <action application="set" data="conference_auto_outcall_caller_id_number=$${effective_caller_id_number}"/>
       <action application="set" data="conference_auto_outcall_profile=default"/>
       
       <action application="conference_set_auto_outcall" data="user/1000@$${domain}"/>
       <action application="conference_set_auto_outcall" data="user/1001@$${domain}"/>
       
       <action application="conference" data="$1@default"/>
       
     </condition>
   </extension>
Nota Bene

If you want, you can also autocall multiple destination at once, just remember to escape your variables if you have more than one or any non-escaped chars in it.

       <action application="conference_set_auto_outcall" data="['var1=a,var2=b']user/1001@$${domain},['var1=c,var2=d']user/1002@$${domain}"/>

 


API Reference

agc

Adjust conference automatic gain control.

conference <confname> agc [on [level]|off]

Examples:

Disable agc:

conference testconf agc off

+OK AGC DISABLED

Enable agc w/ default level:

conference testconf agc on

OK AGC ENABLED 1100

Enable agc w/ specific level:

conference testconf agc on 1120

OK AGC ENABLED 1120

Query agc status:

conference testconf agc

+OK CURRENT AGC LEVEL IS 1100

bgdial

Background dial a destination via a specific endpoint (i.e. call mom from the conference). Similar to dial.

conference <confname> bgdial [{dial string options}]<endpoint_module_name>/<destination> [<callerid_number> [<callerid_name>]]

chkrecord

Query record status of conference. Alternatively, "recording check" syntax may be used.

conference <confname> chkrecord

Examples:

Not recorded:

conference testconf chkrecord

Conference is not being recorded

Recorded:

conference testconf chkrecord

Record file /tmp/foo.wav

Auto recorded:

conference testconf chkrecord

Record file /tmp/foo.wav (Auto)

deaf

Make a conference member deaf.

conference <confname> deaf <[member_id|all|last|non_moderator]>

dial

Dial a destination via a specific endpoint (ie. call mom from the conference).

conference <confname> dial [{dial string options}]<endpoint_module_name>/<destination> [<callerid_number> [<callerid_name>]]

See here for the list of dial string options available: Channel Variables

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.

conference testconf dial {originate_timeout=30}sofia/default/1000@softswitch 1234567890 FreeSWITCH_Conference

The above api call will dial out of a conference named "testconf" to the user located at the specified endpoint with a 30 second timeout. The endpoint will see the call as coming from "FreeSWITCH_Conference" with a caller id of 1234567890.


Also worth noting: values provided in the dial string will overwrite the callerid_number and callerid_name variables provided at the end of the api call.

conference testconf dial {origination_caller_id_name=DialStringName,originate_timeout=30}sofia/default/1000@softswitch 1234567890 FreeSWITCH_Conference

The above api call is almost the same as the previous api call, except the endpoint will see "DialStringName" as the caller id name instead of "FreeSWITCH_Conference".

dtmf

Send DTMF to any member of the conference.

conference <confname> dtmf <[member_id|all|last|non_moderator]> <digits>

 conference testconf dtmf all 134

energy

Adjusts the conference energy level for a specific member.

conference <confname> energy <[member_id|all|last|non_moderator]> [<newval>]

enforce_floor

Give floor status to member.

conference <confname> enforce_floor <member_id|last>

enter_sound

Changes the sound played while entering the conference

conference <confname> enter_sound enter_sound on|off|none|file <filename>

exit_sound

Changes the sound played while leaving the conference

conference <confname> exit_sound enter_sound on|off|none|file <filename>

floor

Toggle floor status of member. That is, give floor to member if no member has it and take away floor if member has floor.

conference <confname> floor <member_id|last>

file_seek

See conference playback. +/- value is relative position in milliseconds. Unsigned value is absolute position in milliseconds.

conference <confname> file_seek [+-]<val>

get

Get runtime parameter of a given conference.

conference <confname> get <parameter_name>

Valid <parameter_name>:

  • run_time (conference time, in seconds)
  • count
  • max_members
  • rate
  • profile_name
  • sound_prefix
  • caller_id_name
  • caller_id_number
  • is_locked
  • endconf_grace_time (in seconds)
  • uuid
  • wait_mod

Output: current value of a given parameter:

  • for run_time, count, max_members, rate, endconf_grace_time: a number (converted to string).
  • for is_locked: string "locked" if locked or empty if not.
  • for wait_mod: string "true" if set or empty if not.
  • for others: string value.

It can be also used in a dialplan:

<action application="set" data="conf_runtime=${conference(${conference_name} get run_time)}"/>
<action application="set" data="conf_sounddir=${conference(${conference_name} get sound_prefix)}"/>

hup

Kick without the kick sound

conference <confname> hup <[member_id|all|last|non_moderator]>

kick

Kicks a specific member or all members from a conference.

conference <confname> kick <[member_id|all|last|non_moderator]>

list

Lists a specific conference member or all members.

conference list [delim <string>]

conference <confname> list [delim <string>]

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:

<extension name="late entry">
   <condition field="destination_number" expression="^(300\d)$" />
   <condition field="${conference $1 list count}" expression="^\d+">
      <action application="conference" data="$1@default++flags{nomoh}"/>
   </condition>
</extension>

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.

lock

Lock a conference so no new members will be allowed to enter.

conference <confname> lock

mute

Mutes a specific member in a conference.

conference <confname> mute <[member_id|all|last|non_moderator]>

nopin

Removes a pin for a specific conference.

conference <confname> nopin

norecord

conference testconf norecord all

Or,

conference testconf norecord /tmp/foo.wav

pause

Pause a conference recording. See also recording API for alternative syntax.

conference <confname> pause <file_path>

pause_play

Pause conference playback.

conference <confname> pause_play

pin

Sets or changes a pin number for a specific conference.

conference <confname> pin <pin#>

Please note that if you set a conference pin and then issue a command like

conference <confname> dial sofia/default/123456@softswitch

123456 will not be challenged with a pin, he will just join the conference named <confname>.

play

Play an audio file in a conference to all members or to a specific member. You can stop that same audio with the Stop command below.

conference <confname> play <file_path> [<async>|<member_id>]

record

conference testconf record /tmp/foo.wav

recording

Alternative syntax for all recording related commands:

conference <confname> recording start <file_path>
conference <confname> recording check <confname>
conference <confname> recording stop <file_path>|all
conference <confname> recording pause <file_path>
conference <confname> recording resume <file_path>

relate

Mute or Deaf a specific member to another member.

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

Examples:

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

resume

Resume recording. See also recording API for alternative syntax.

conference <confname> resume <file_path>

say

Say text in a conference to all members.

conference <confname> say <text>

saymember

Say text to a specific member in a conference.

conference <confname> saymember <member_id> <text>

set

Set runtime parameter of a given conference.

conference <confname> set <parameter_name> <value>

Valid <parameter_name>:

  • max_members
  • sound_prefix
  • caller_id_name
  • caller_id_number
  • endconf_grace_time

Output: previous value of a given parameter.

It can be also used in a dialplan:

<action application="set" data="conf_oldsound=${conference(${conference_name} set sound_prefix ${sound_prefix_pl})}"/>
<action application="set" data="void_result=${conference(${conference_name} set endconf_grace_time 300)}"/>

stop

Stops any queued audio from playing. See also recording API for alternative syntax.

conference <confname> stop <[current|all]> [<member_id>]

tmute

Toggles mutes on/off for a specific member in a conference.

conference <confname> tmute <[member_id|all|last|non_moderator]>

transfer

Transfer a member from one conference to another conference.

conference <confname> transfer <conference_name> <member_id>

To transfer a member to another extension use the api transfer command with the uuid of their session.

undeaf

Allow a specific member to hear again.

conference <confname> undeaf <[member_id|all|last|non_moderator]>

unlock

Unlock a conference so that new members can enter.

conference <confname> unlock

unmute

Unmute a specific member of a conference.

conference <confname> unmute <[member_id|all|last|non_moderator]>

volume_in

Adjusts the input volume for a specific conference member. This changes the loudness of the specified member's microphone into the conference.

conference <confname> volume_in <[member_id|all|last|non_moderator]> [<newval>]

volume_out

Adjusts the output volume for a specific conference member. This changes the loudness of the conference out to the specified member's earpiece.

conference <confname> volume_out <[member_id|all|last|non_moderator]> [<newval>]

xml_list

Lists all or a specific conference members in XML format.

conference <confname> xml_list

Event Socket Use

You can subscribe to the following to receive conference events:

 conference::maintenance

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"/>
  </profile>

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.

Channel variables set by mod_conference

conference_last_matching_digits

Contains the last matching digits that the user on this channel sent into the conference.

Usage:

<action application="log" data="INFO Last digits sent by this user: ${conference_last_matching_digits}"/>


conference_member_id

Contains the conference_member_id value for any conference to which the channel may be connected.


conference_moderator

Is true if the channel is connected to a conference as a moderator.


conference_name

The name of the last conference joined by this channel.

Usage:

<action application="log" data="INFO Last conference joined by this user: ${conference_name}"/>


conference_recording

Contains the file name of the conference recording for the conference to which the channel is connected.


conference_uuid

Every instance of a conference has its own UUID. This channel variable stores the conference UUID for the most recent conference in which the channel was a member. It is set as soon as the channel enters the conference, and will show up in XML CDRs and uuid_dump calls, as well as any events that show channel variables.


last_transferred_conference

Contains the name of the last conference that this channel was connected to.

Usage:

<action application="log" data="INFO Last conference this person visited was [${last_transferred_conference}]"/>


Channel variables to control mod_conference behavior

conference_auto_outcall_announce

File name of audio message to play to conference member joining conference via the conference_set_auto_outcall application. Because the conference would be originating an outbound call to a member this typically would be a greeting with an explanation that the recipient will be joining a conference call.


Usage:

<action application="set" data="conference_auto_outcall_announce=sounds/soundfile.wav"/>


conference_auto_outcall_caller_id_name

Caller ID name to use when dialing endpoints to join the conference via the conference_set_auto_outcall application.

Usage:

<action application="set" data="conference_auto_outcall_caller_id_name=$${effective_caller_id_name}"/>


conference_auto_outcall_caller_id_number

Caller ID number to use when dialing endpoints to join the conference via the conference_set_auto_outcall application.

Usage:

<action application="set" data="conference_auto_outcall_caller_id_number=${effective_caller_id_number}"/>


conference_auto_outcall_flags

Conference flags to set for members joining conference via the conference_set_auto_outcall application

Usage:

<action application="set" data="conference_auto_outcall_flags=mute"/>


conference_auto_outcall_maxwait

Maximum time in seconds that the channel that initiated the conference_set_auto_outcall will wait for members to join the conference.

Usage:

<action application="set" data="conference_auto_outcall_maxwait=10"/>


conference_auto_outcall_prefix

The value of conference_auto_outcall_prefix is prepended to each of conference_set_auto_outcall values, of which there can be more than one.

Usage:

  <extension name="mad_boss_intercom">
    <condition field="destination_number" expression="^0911$">
      <action application="set" data="conference_auto_outcall_caller_id_name=Mad Boss1"/>
      <action application="set" data="conference_auto_outcall_caller_id_number=0911"/>
      <action application="set" data="conference_auto_outcall_timeout=60"/>
      <action application="set" data="conference_auto_outcall_flags=mute"/>
      <action application="set" data="conference_auto_outcall_prefix={sip_auto_answer=true,execute_on_answer='bind_meta_app 2 a s1 transfer::intercept:${uuid} inline'}"/>
      <action application="set" data="sip_exclude_contact=${network_addr}"/>
      <action application="conference_set_auto_outcall" data="${group_call(sales)}"/>
      <action application="conference" data="madboss_intercom1@default+flags{endconf|deaf}"/>
    </condition>
  </extension>


conference_auto_outcall_profile

Conference profile to use for members joining the conference via the conference_set_auto_outcall application.

Usage:

<action application="set" data="conference_auto_outcall_profile=default"/>


conference_auto_outcall_timeout

Originate timeout to use when joining a member to a conference via conference_set_auto_outcall.

Usage:

<action application="set" data="conference_auto_outcall_timeout=60"/>


conference_controls

Set this variable to specify which conference control set to use when transferring a caller into a conference. This allows you, for example, to have a control set for the conference moderator and another control set for regular conference members. The control set for the moderator could include the ability to mute or kick people, for example.

NOTE: You must create the desired conference control set. Also, if this is not set then the default conference control set is used for the conference member.

Usage:

<action application="set" data="conference_controls=moderator"/>


conference_enforce_security

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. This channel variable allows the behavior to be modified.


Usage:

Inbound

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

Outbound

originate {conference_enforce_security=true}sofia/internal/1001 &conference(3000)


conference_enter_sound

When set, this channel variable will override the enter-sound param on conference profile for any conferences into which the call leg is transferred.

Usage:

<action application="set" data="conference_enter_sound=silence_stream://10"/>


conference_exit_sound


Usage:

<action application="set" data="conference_exit_sound=silence_stream://10"/>


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. Asterisk ships with some useful free sound files for conferences.

See Also