<Conference> noun

<Dial> verb's <Conference> noun allows the connection to a named conference room.
For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Room 1234</Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('Room 1234')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('Room 1234');
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("Room 1234");

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('Room 1234')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('Room 1234')
  end
end

puts response.to_s

Noun Attributes

Attribute
muted optionalWhether or not a caller can speak in a conference. Default is false.
beep optionalWhether or not a sound is played when callers leave or enter a conference. Default is true. See below for all possible values.
startConferenceOnEnter optionalThe conference begins once a specific caller enters into the conference room, unless it has already started. If a participant joins and startConferenceOnEnter is false, that participant will hear background music and stay muted until a participant with startConferenceOnEnter set to true joins the call. Default is true.
endConferenceOnExit optionalIf a participant with endConferenceOnExit set to true leaves a conference, the conference terminates and all participants drop out of the call. Default is false.
waitUrl optionalURL for the music to play in the background while participants are waiting to enter a conference room. Only supports <Play>, <Pause>, and <Redirect>. If no waitUrl is provided, SignalWire will use its hold music.
waitMethod optionalSpecifies whether the request to waitUrl is a GET or a POST. The default value is POST.
maxParticipants optionalThe maximum number of participants allowed in a named conference room.
record optionalCan be used to record an entire <Conference>. record-from-start will begin recording the conference call once the first two participants join in on the call. Wait music is not recorded. Default is do-not-record.
trim optionalWhether or not silence in the beginning and end of recordings are removed. Default value trim-silence follows this behavior.
coach optionalCoach accepts a call SID of a call that is currently connected to an in-progress conference. Specifying a call SID that does not exist or is no longer connected to the conference will result in the call failing to the action URL and throwing a 13240 error.
statusCallbackEvent optionalWhich conference state changes will trigger a webhook to the URL provided in statusCallback. Specifies conference state changes. The first participant to join the named conference is able to manipulate and set events. All other changes made by other participants will be ignored. See below for all possible events. To specify multiple events, separate them with a space.
statusCallback optionalThe URL to make requests to for each statusCallbackEvent event. The URL is set by the first participant to enter a conference. All other information provided by other participants will be ignored. See below for request parameters.
statusCallbackMethod optionalThe type of HTTP request to use when requesting a statusCallback. Default is POST.
recordingStatusCallback optionalThe recordingStatusCallback attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL when recording is accessible. See below for request parameters.
recordingStatusCallbackMethod optionalThe type of HTTP request to use when requesting a recordingStatusCallback. Default is POST.
recordingStatusCallbackEvent optionalSpecifies recording status changes. To specify multiple values, separate them by a space. Default is completed and failed. See below for details.
eventCallbackUrl optionalThe 'eventCallbackUrl' attribute takes a URL as an argument and makes a POST request to it when a conference ends.

Values for the beep attribute

The beep attribute has the following values:

Value
true Plays a beep when a caller leaves or enters a conference. The default value for beep.
false Disables the beep when callers leave and enter conferences.
onEnter Only plays a beep when a caller enters a conference.
onExit Only plays a beep when a caller leaves a conference.

Events for the statusCallbackEvent attribute

The statusCallbackEvent attribute has the following events:

Event
start The conference has started as long as there are at least two people in the conference room and one of the participant's startConferenceOnEnter is set to true.
end The conference ends when the last participant in the call or a participant with endConferenceOnExit set to true leaves the call.
join When a participant joins a conference.
leave When a participant leaves a conference.
mute When a participant has been muted or un-muted.
hold When a participant has been put on hold or put out of hold.
speaker When a participant has begun or stopped speaking.

Request parameters for the statusCallback URL

You can expect several parameters to be present in the request associated to the statusCallback URL. First, you have the Standard Request Parameters. Then, you also have the following specific parameters:

Parameter
ConferenceSid stringA unique identifier for the named Conference.
FriendlyName stringName of the conference.
AccountSid stringA unique identifier for the Account this call is associated with.
Timestamp stringThe timestamp, in RFC 2822 format, of when an event occurred.
StatusCallbackEvent stringConference state changes. Possible events are: conference-end, conference-start, participant-leave, participant-join, participant-mute, participant-unmute, participant-hold, participant-unhold, participant-speech-start, participant-speech-stop.
CallSid stringA unique identifier for the call.
Muted stringWhether a participant is muted or not.
Hold stringWhether a participant is on hold or not.
EndConferenceOnExit stringWhen a participant has this set on true and they leave a call, conference ends.
StartConferenceOnEnter stringWhen a participant has this set on true and they join a call, conference begins.
EventName stringThe name of the event.
RecordingUrl stringThe URL of the recorded audio file.
Duration integerThe time, in seconds, of the conference call.
RecordingFileSize stringThe size of the recorded audio file.

Request parameters for the recordingStatusCallback URL

The recordingStatusCallback request contains the following parameters:

Parameter
AccountSid stringA unique identifier for the Account this recording is associated with.
ConferenceSid stringA unique identifier for the Conference this recording is associated with.
RecordingSid stringThe unique identifier for the recording.
RecordingUrl stringThe URL for the audio recording.
RecordingStatus stringThe status of the recording. Possible values are: in-progress, complete, failed.
RecordingDuration integerThe duration, in seconds, of the recording.
RecordingChannels integerThe number of channels in the recording. Only 1 channel is supported for conference recordings.
RecordingStartTime integerThe timestamp for when the recording started.
RecordingSource stringThe type of call that initiated the recording.

Status values for the recordingStatusCallbackEvent attribute

The recordingStatusCallbackEvent attribute has the following status values:

Value
in-progress The recording has begun.
completed The recording has completed and is accessible.
failed The recording is not accessible because of a failure.

Examples

A Simple Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Room 1234</Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('Room 1234')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('Room 1234');
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("Room 1234");

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('Room 1234')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('Room 1234')
  end
end

puts response.to_s

The first participant would join the conference "Room 1234" and listen to wait music in the background until a second participant joins the conference. Once participants have joined the conference, the wait music comes to an end, a beep is played, and the conference call begins.

A Moderated Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference startConferenceOnEnter="false">
      moderated-conference-room
    </Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('moderated-conference-room', { startConferenceOnEnter: false })
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('moderated-conference-room', array( 'startConferenceOnEnter' => false ));
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("moderated-conference-room",
            startConferenceOnEnter: false);

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('moderated-conference-room', start_conference_on_enter=False)
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('moderated-conference-room', start_conference_on_enter: false)
  end
end

puts response.to_s

You can set the startConferenceOnEnter to false so that a group of participants can join in the conference room but the conference cannot begin until the moderator has entered the call. As the participants wait for the conference to begin, hold music will be playing in the background.

Start A Moderated Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
      moderated-conference-room
    </Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('moderated-conference-room', { startConferenceOnEnter: true, endConferenceOnExit: true })
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('moderated-conference-room', array(
    'startConferenceOnEnter' => true,
    'endConferenceOnExit' => true )
  );
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("moderated-conference-room",
            startConferenceOnEnter: true, endConferenceOnExit: true);

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('moderated-conference-room', start_conference_on_enter=True, end_conference_on_exit=True)
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('moderated-conference-room', start_conference_on_enter: true, end_conference_on_exit: false)
  end
end

puts response.to_s

Now, since the moderator has joined in on the conference call, startConferenceOnEnter is set to true which means the conference can begin. All the participants that were waiting on hold will now be connected to the conference room; the hold music will come to an end and a beep notification will play indicating conference entrance. Once the moderator leaves the call, the conference will come to an end and all participants will be disconnected from the call.

Joining a Conference Call Muted (Monitor)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference muted="true">ConferenceRoom</Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference({ muted: true }, 'ConferenceRoom')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('ConferenceRoom', array( 'muted' => true ));
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("ConferenceRoom", muted: true);

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('ConferenceRoom', muted=True)
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('ConferenceRoom', muted: true)
  end
end

puts response.to_s

Participants who enter a conference call muted can hear the other participants in the call who are unmuted. However, the unmuted participants cannot hear the muted callers. Muting and unmuting can be enabled and disabled in real-time via a REST API.

Coaching A Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference coach="AgentCallSid">
      Example-Room
    </Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('Example-Room', { coach: "AgentCallSid" })
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('Example-Room', array( 'coach' => 'AgentCallSid' ));
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("Example-Room",
            coach: 'AgentCallSid');

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('Example-Room', coach='AgentCallSid')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('Example-Room', coach: '')
  end
end

puts response.to_s

Recording a Conference Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference record="record-from-start"
                recordingStatusCallback="https://www.example.com/recording_update">
      ConferenceCall
    </Conference>
  </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.conference('ConferenceCall', { record: 'record-from-start', recordingStatusCallback: 'https://www.example.com/recording_update' })
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->conference('ConferenceCall', array(
    'record' => 'record-from-start',
    'recordingStatusCallback' => 'https://www.example.com/recording_update' )
  );
  echo $response;
?>
using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("ConferenceCall", record: "record-from-start",
            recordingStatusCallback: new Uri("https://www.example.com/recording_update"));

        response.Append(dial);
        Console.WriteLine(response.ToString());;
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('ConferenceCall', record='record-from-start', recording_status_callback='https://www.example.com/recording_update')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('ConferenceCall', record: 'record-from-start', recording_status_callback: 'https://www.example.com/recording_update')
  end
end

puts response.to_s

The recording of the conference call will begin when at least two participants join the conference room. A recordingStatusCallback will be sent when the recording is accessible.

Notes On Usage

  • You can freely name the conference room to fit your preference. However, only callers within a project can join in on a named conference room. Callers from separate projects will not be able to connect to that same conference room.
  • You can customize the background music as callers are waiting to join a conference call
  • Conferences will not begin unless there are 2 or more parties present.