The <Conference> element allows you to connect to a named conference room and talk with the other callers who have also connected to that room.

The name of the room is up to you. This means that any caller who joins ‘room9876′ will end up in the same conference room. The maximum number of members in a single conference room is limited by the resources on your system.

By default, the conference rooms enable a number of useful features:

  • Conferences do not start until at least two members join.
  • While waiting, custom waiting music is played.
  • When members enter and exit, notification sounds can be played to inform the other members.

You can configure or disable each of these features based on your particular needs.

Element Attributes

The <Conference> element supports the following attributes that modify its behavior:

Attribute Name Allowed Values Default Value
muted true, false false
enterSound "", "beep:1", "beep:2" “”
exitSound "", "beep:1", "beep:2" “”
startConferenceOnEnter true, false true
endConferenceOnExit true, false false
stayAlone true, false true
waitSound absolute URL No Music
maxMembers Any integer > 0 200
timeLimit Any integer >= 0 (0 is No Limit) 0
hangupOnStar true, false false
recordFilePath Any file path, where recording of the conference will be stored. No path indicates no recording none
recordFileFormat wav, mp3 mp3
recordFileName String value to be used as file name for the recording. If empty, a unique name will be used. none
action absolute URL. no default action for Conference
method GET, POST POST
callbackUrl absolute URL none
callbackMethod GET, POST POST
digitsMatch List of digits patterns separated by comma none
floorEvent true, false false
  • muted: This attribute lets you specify whether a member can speak on the conference. If this attribute is set to ‘true’, the member will only be able to listen to people on the conference. This attribute defaults to ‘false’.
  • enterSound: This attribute lets you specify a single beep or a double beep to be played to the conference when a member enters the conference. By default no beep is played.
  • exitSound: This attribute lets you specify a single beep or a double beep to be played to the conference when a member exits the conference. By default no beep is played.
  • startConferenceOnEnter: This attribute tells a conference to start when this member joins the conference, if it is not already started. This is true by default. If this is false and the member joins a conference that has not started, they are muted and hear background music until a member joins where startConferenceOnEnter is true. This is useful for implementing moderated conferences.
  • endConferenceOnExit: When all participants with this attribute set to ‘true’ have left, the conference ends and all others members drop out. This defaults to ‘false’. This is useful for implementing moderated conferences.
  • stayAlone: When a participant is alone in a conference and this attribute is set to ‘false’ for him, the conference ends and he’s dropped out. This defaults to ‘true’.
  • waitSound: The ‘waitSound’ attribute is a remote URL fetched with POST HTTP request which must return a RESTXML with Play and/or Wait Elements only (all others are ignored). This RESTXML is played to the Member while alone in the Conference.
  • maxMembers: This attribute indicates the maximum number of members you want to allow within a the named conference room. The default maximum number of members is 200.
    This value can be a any positive integer greater than 0.
  • timeLimit: This attribute sets the maximum duration of the conference in seconds. For example, by setting a time limit of 600 seconds conference will finish automatically after ten minutes. By default, it is set to 0, which indicates no time limit.
  • hangupOnStar: This attribute lets the member exit from the conference by pressing the ‘*‘ key on his phone, without having to hang up their phone. Plivo will continue on to the next element in the current RESTXML document, after exit.
  • recordFilePath: This attribute will decide if the conference is recorded or not. Setting a path here will record the conference, and the recording will be saved in the respective path. By default this value is none, and hence recording is disabled.
  • recordFileFormat: This attribute defines the format in which recording of the conference is saved. It can be ‘wav’ or ‘mp3′.
  • recordFileName: If provided this name will be used for the recording. If empty or not set, a unique name will be generated.
  • action: Redirect to this URL after leaving conference.
  • method: Submit to ‘action’ url using GET or POST.
  • callbackUrl: If set, url to request when call enters and leaves conference or has pressed digits matching (digitsMatch) or is the floor holder (floorEvent).
  • callbackMethod: Submit to ‘callbackUrl’ url using GET or POST.
  • digitsMatch: A list of matching digits to send with callbackUrl. Can be a list of digits patterns separated by comma.
  • floorEvent: If this attribute is set to ‘true’, send notification to callbackUrl when member is the floor holder. This defaults to ‘false’.
Request Parameters for action
Parameter Description
ConferenceName The conference room name.
ConferenceUUID The conference unique ID.
ConferenceMemberID ID of call in the conference
CallbackUrl Request Parameters for callbackUrl
Parameter Description
ConferenceName The conference room name.
ConferenceUUID The conference unique ID.
ConferenceMemberID ID of call in the conference
ConferenceAction ‘enter’ if call has entered conference, ‘exit’ if call has left conference,
‘digits’ if call has pressed digits matching (see digitsMatch), ‘floor’if call is the floor holder into conference (see floorEvent).
ConferenceDigitsMatch Only set if ConferenceAction is ‘digits’. The digits pattern matching when call has pressed digits.

Examples

Example 1: A Simple Conference

The first caller to execute this RESTXML would join conference room 9876 and listen to the waiting music, if any. When the next caller executes this RESTXML, they would join the same conference room and the conference would start. The wait music ends, the entrySound is played and all parties can communicate.

1
2
3
<Response>
    <Conference>9876</Conference>
</Response>

Example 2: A Moderated Conference

First, you can drop a number of people into the conference, specifying that the conference
shouldn’t yet start:

1
2
3
<Response>
    <Conference startConferenceOnEnter="false">9876</Conference>
 </Response>

Each person will hear hold music while they wait. When the “moderator”
calls in, you can specify that the conference should begin:

1
2
3
4
5
<Response>
     <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
      9876
    </Conference>
</Response>

Also note that since the moderator has “endConferenceOnExit=’true’” set, then when the moderator hangs up,
the conference will end and each participant’s <Dial> will complete.

Example 3: Join a Conference Muted

This code allows forces participants to join the conference room muted. They can hear what unmuted participants are saying but no one can hear them.

1
2
3
<Response>
    <Conference muted="true">SimpleRoom</Conference>
</Response>

Example 4: Bridging Incoming Calls

Sometimes you just want to bridge two incoming calls together. With this minimal conferencing attribute setup, no wait music or entrySound is played, participants can speak right away as they join, and the conference ends right away if either participant hangs up.

1
2
3
4
5
<Response>
    <Conference beep="false" waitSound="" startConferenceOnJoin="true" endConferenceOnExit="true">
      NoMusicNoBeepRoom
    </Conference>
</Response>

Example 5: Call on Hold

1
2
3
4
5
<Response>
    <Conference beep="false">
      Customer Waiting Room
    </Conference>
</Response>

This code puts the first caller into a waiting room, where they’ll hear music. It’s as if they’re on hold, waiting for an agent or operator to help them.

Then, when the operator or agent is ready to talk to them… their call would execute:

1
2
3
4
5
<Response>
    <Conference beep="false" endConferenceOnExit="true">
      Customer Waiting Room
    </Conference>
</Response>

This code would join the operator with the person who was holding. Because the conference starts when they enter, the wonderful hold music the first person was hearing will stop, and the two people will begin talking. Because “beep=’false’”, the caller won’t hear a ding when the agent answers, which is probably appropriate for this use case. When the operator hangs up, then ‘endConferenceOnExit’ will cause the conference to end.

Example 6: Combining with Other attributes

You can set a timeLimit, after which you’ll be removed from the conference. You can turn on hangupOnStar, which lets you leave a conference by pressing the * key. You can specify a <redirect> element, so that after you leave the conference room Plivo will submit to the redirect url and your web app can respond with new RESTXML and continue your call.

1
2
3
4
<Response>
    <Conference hangupOnStar="true" timeLimit="30">Love FreeSWITCH</Conference>
    <Redirect>http://www.foo.com/nextstep/</Redirect>
</Response>

Example 7: Using callbackUrl

Using this code, when call enters and leaves conference, a POST http request is sent to http://www.foo.com/confevents/.
When user press #0 or 99 or 000, a POST http request is sent to http://www.foo.com/confevents/.

(see CallbackUrl Request Parameters for more infos on http data sent).

1
2
3
4
5
<Response>
    <Conference callbackUrl="http://www.foo.com/confevents/" callbackMethod="POST" digitsMatch="#0,99,000">
      MyRoom
    </Conference>
</Response>

Comments are closed.