Plivo Cloud | Conference

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. There is no limit to the maximum number of members in a single conference room.

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	200
`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`

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`.

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.
`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:

Sets the timeLimit attribute, after which the member will be removed from the conference.
Sets hangupOnStar to true, which enables the user to leave a conference by pressing the * key.
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>
```