The Conference Element

The <Conference> element is used for starting a conference and callers can then join in to talk to others connected to that room.

The user can choose the name of the room.The room names are mapped to a user account, which means that two accounts with same room name will be dialing into different conferences. Maximum number of members in a single conference room is 100

The following attributes are supported by the <Conference> element:

Element Attributes

Attribute Name Description Allowed Values Default Value
muted To mute a member who joins a conference, set this attribute to 'true'; the member will be able to listen to the people in the conference. true, false false
enterSound Used to play a sound when a member enters the conference. A single beep is played with beep:1 value and a double beep is played with a beep:2 value. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML with Play, Speak and/or Wait elements only. All other elements are ignored. "", "beep:1", "beep:2" or valid URL “”
exitSound Used to play a sound when a member exits the conference. Defaults to no beep. A single beep is played with beep:1 value and a double beep is played with a beep:2 value. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML with Play, Speak and/or Wait elements only. All other elements are ignored. "", "beep:1", "beep:2" or a valid URL “”
startConferenceOnEnter When a member joins the conference with this attribute set to true, the conference is started (if not already in progress). If a member joins a conference that has not yet started, with this attribute value set to false, the member is muted and hears background music until another member joins the conference. This attribute is handy when organizing moderated conferences. true, false true
endConferenceOnExit If a member with this attribute set to true leaves the conference, the conference ends and all other members are automatically removed from the conference. This attribute is handy when organizing moderated conferences. true, false false
stayAlone When a member is alone in a conference and has this attribute set to false, the conference ends and the member is dropped. true, false true
waitSound Is a remote URL fetched with HTTP POST request. The URL must return an XML document with Play, Speak and/or Wait elements only. All other elements are ignored. The sound instructed by the XML response is played to the member while alone in the conference. absolute URL No Music
maxMembers Indicates the maximum number of members that are to be allowed within a named conference room. This value can be any positive integer greater than 0. When maxMembers is reached, the conference is skipped. If the next element in the XML response is the action_url this is also skipped and the call proceeds to the next element after the <Conference> element. Any integer > 0 and <= 100 100
record None true or false false
recordFileFormat The file format for recording. mp3 or wav mp3
timeLimit Used to set the maximum duration of the conference in seconds. For example, a time limit of 600 seconds will automatically end the conference after ten minutes. Defaults to 0, which indicates that no time limit is set. Any integer >= 0 0
hangupOnStar If set to true, this attribute lets the member exit from the conference by pressing the ‘*‘ key on their phone, without having to hang up. The Plivo API will continue on to the next element in the current XML document, after exit. true, false false
action Should be an absolute URL to which the API can send back parameters. See the action Request Parameters table below for more information. absolute URL. no default action for Conference
method Submit to action URL using GET or POST. GET, POST POST
callbackUrl If specified, information is sent back to this URL. See the callbackUrl Request Parameters table below for more information. absolute URL none
callbackMethod Method used to notify callbackUrl using GET or POST. GET, POST POST
digitsMatch A list of digits that are sent to the callbackUrl when the digits pressed by the user match the digitsMatch parameter. List of digits patterns separated by comma. none
floorEvent If this attribute is set to ‘true’, send notification to callbackUrl when member is the floor holder. true,false false
redirect If false, do not redirect to action URL, only request the URL and continue to next element. true,false true
transcriptionType The type of transcription required.
  • auto - Transcription is completely automated; turnaround time is about 5 minutes.
  • hybrid - Transcription is a combination of automated and human verification processes; turnaround time is about 10-15 minutes.
auto
transcriptionUrl The URL where the transcription is available. absolute URL none
transcriptionMethod The method used to invoke the transcriptionUrl. GET, POST GET
relayDTMF Transmit all digits except digitsMatch to all members of conference. true, false true

action Request Parameters

The following parameters are sent to the action URL if the action parameter is specified.

Parameter Description
ConferenceName The conference room name.
ConferenceUUID Unique ID of the conference.
ConferenceMemberID Member ID in the conference
RecordUrl URL of the recorded file. Only available if record is set to true.
RecordingID ID of the recorded file. Only available if record is set to true.

callbackUrl Request Parameters

The following parameters are sent to the callback URL if callbackUrl is specified.

Parameter Description
ConferenceAction ‘enter’ when user enters the conference, ‘exit’ when user leaves the conference, ‘digits’ when user presses matching digits ‘floor’if user is the floor holder in the conference ‘record’if conference has been recorded using record attribute.
ConferenceName The conference room name.
ConferenceUUID Unique ID of the conference.
ConferenceMemberID ID of call in the conference. (Not present if ConferenceAction is ‘record’)
CallUUID Unique identifier for this call. (Not present if ConferenceAction is ‘record’)
ConferenceDigitsMatch Sent if ConferenceAction is ‘digits’.
The digits pattern matching when call has pressed digits.
RecordUrl Sent if ConferenceAction is set to record attribute.
The URL of the recorded file.
RecordingID Sent if ConferenceAction is set to record attribute.
The ID of the recorded file.
RecordingDuration Sent if ConferenceAction is set to record attribute.
Duration of recording in seconds. If recordSession or startOnDialAnswer is true, the duration is always -1.
RecordingDurationMs Sent if ConferenceAction is set to record attribute.
Duration of recording in milliseconds.
RecordingStartMs Sent if ConferenceAction is set to record attribute.
When the recording started (epoch time UTC) in milliseconds.
RecordingEndMs Sent if ConferenceAction is set to record attribute.
When the recording ended (epoch time UTC) in milliseconds.

Example 1: A Simple Conference

The first caller to execute this XML joins the conference room 9876. When the next caller executes this XML, the caller will join the same conference room and the conference will start.

  <Response>
    <Conference>9876</Conference>
  </Response>

Example 2: A Moderated Conference

A caller will be able to join the conference room 9876 and will hear music, but the conference will not start until the moderator joins the conference.

  <Response>
    <Conference startConferenceOnEnter="false" waitSound="http://www.foo.com/waitmusic/">9876</Conference>
  </Response>

Next, the moderator has set endConferenceOnExit to true, so when the moderator hangs up, the conference will end. and each participant will also exit the conference.

  <Response>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">9876</Conference>
  </Response>

Example 3: Join a Conference Muted

This code forces participants to join the conference room muted. They can hear the unmuted participants speak.

  <Response>
    <Conference muted="true">SimpleRoom</Conference>
  </Response>

Example 4: Bridging Incoming Calls

The following code bridges two incoming calls together. With this minimal conferencing attribute setup, no sound is played, participants can speak as soon as they join, and the conference ends immediately when a participant hangs up.

  <Response>
    <Conference beep="false" waitSound="http://www.foo.com/waitmusic/" startConferenceOnEnter="true">
  endConferenceOnExit="true">NoMusicNoBeepRoom</Conference>
  </Response>

Example 5: Call on Hold

This code places the first caller into a waiting room, where the caller will hear music. It is similar to placing a caller on hold, waiting for an agent or operator to help them.

  <Response>
    <Conference waitSound="http://www.foo.com/waitmusic/" beep="false">Customer Waiting Room</Conference>
  </Response>

This code enables the operator to join the person who was put on hold in the Conference room. The conference starts when the operator enters the room and the hold music the first caller was listening to, will stop. “beep=’false’”, therefore the caller will not hear any sound when the agent answers. When the moderator hangs up, since the endConferenceOnExit is set to 'true', the conference will end.

  <Response>
    <Conference beep="false" endConferenceOnExit="true">Customer Waiting Room</Conference>
  </Response>

Example 6: Combining with Other Attributes

This code performs the following actions:

  1. Sets the timeLimit attribute, after which the member will be removed from the conference.
  2. Sets hangupOnStar to true, which enables the user to leave a conference by pressing the * key.
  3. Specifies a <redirect> element, so that after the member leaves the room, the redirect URL specified by the Redirect element is invoked.

      <Response>
        <Conference hangupOnStar="true" timeLimit="30">plivo</Conference>
        <Redirect>http://www.foo.com/nextstep/</Redirect>
      </Response>
    

Example 7: Using callbackUrl

When a member enters and leaves conference, an HTTP POST request is sent to the specified callbackUrl. When the user presses the digits that match with the digitsMatch parameter, an HTTP POST request is sent to the callbackUrl.

See the callbackUrl Request Parameters table above for a list of parameters that are sent to the callback URL.

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