***

id: e5546e8d-e24b-42d6-a6e2-ee343874f46f
title: Conference
sidebar-title: Conference
slug: /cxml/reference/voice/conference
position: 1
max-toc-depth: 3
----------------

[`<Dial>`](/docs/compatibility-api/cxml/reference/voice/dial) verb's `<Conference>` noun allows the connection to a named conference room.
For example:

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference>Room 1234</Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference("Room 1234");
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  from signalwire.voice_response import VoiceResponse, Dial, Conference

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

  print(response)
  ```

  ```ruby
  require 'signalwire/sdk'

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

  puts response.to_s
  ```
</CodeBlocks>

## Noun attributes

<ParamField path="beep" type="string" default="true">
  Whether or not a sound is played when callers leave or enter a conference. See [below](#conference_beep) for all possible values.
</ParamField>

<ParamField path="coach" type="string">
  Coach accepts a call [SID](/docs/platform/what-is-a-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.
</ParamField>

<ParamField path="endConferenceOnExit" type="boolean" default="false">
  If a participant with `endConferenceOnExit` set to **true** leaves a conference, the conference terminates and all participants drop out of the call.
</ParamField>

<ParamField path="eventCallbackUrl" type="string">
  The `eventCallbackUrl` attribute takes a URL as an argument and makes a `POST` request to it when a conference ends.
</ParamField>

<ParamField path="maxParticipants" type="integer">
  The maximum number of participants allowed in a named conference room.
</ParamField>

<ParamField path="muted" type="boolean" default="false">
  Whether or not a caller can speak in a conference.
</ParamField>

<ParamField path="record" type="string" default="do-not-record">
  Can 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.
</ParamField>

<ParamField path="recordingStatusCallback" type="string">
  The `recordingStatusCallback` attribute takes in an absolute URL. SignalWire will make a `GET` or `POST` request to this URL when recording is accessible. See [below](#conference_recordingStatusCallback) for request parameters.
</ParamField>

<ParamField path="recordingStatusCallbackEvent" type="string" default="completed failed">
  Specifies recording status changes. To specify multiple values, separate them by a space. See [below](#conference_recordingStatusCallbackEvent) for details.
</ParamField>

<ParamField path="recordingStatusCallbackMethod" type="string" default="POST">
  The type of HTTP request to use when requesting a `recordingStatusCallback`.
</ParamField>

<ParamField path="startConferenceOnEnter" type="boolean" default="true">
  The 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.
</ParamField>

<ParamField path="statusCallback" type="string">
  The 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](#conference_statusCallback) for request parameters.
</ParamField>

<ParamField path="statusCallbackEvent" type="string">
  Which 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](#conference_statusCallbackEvent) for all possible events. To specify multiple events, separate them with a space.
</ParamField>

<ParamField path="statusCallbackMethod" type="string" default="POST">
  The type of HTTP request to use when requesting a `statusCallback`.
</ParamField>

<ParamField path="trim" type="string" default="trim-silence">
  Whether or not silence in the beginning and end of recordings are removed.
</ParamField>

<ParamField path="waitMethod" type="string" default="POST">
  Specifies whether the request to `waitUrl` is a `GET` or a `POST`.
</ParamField>

<ParamField path="waitUrl" type="string">
  URL 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.
</ParamField>

#### Values for the `beep` attribute  \[#conference\_beep]

The `beep` attribute has the following values:

| Value     | Description                                                                                 |
| :-------- | :------------------------------------------------------------------------------------------ |
| `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  \[#conference\_statusCallbackEvent]

The `statusCallbackEvent` attribute has the following events:

| Event     | Description                                                                                                                                                          |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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  \[#conference\_statusCallback]

You can expect several parameters to be present in the request associated to the `statusCallback` URL. First, you have the [Standard Request Parameters](/docs/compatibility-api/cxml/reference/voice#request-parameters). Then, you also have the following specific parameters:

<ParamField path="AccountSid" type="string">
  A unique identifier for the Account this call is associated with.
</ParamField>

<ParamField path="CallSid" type="string">
  A unique identifier for the call.
</ParamField>

<ParamField path="ConferenceSid" type="string">
  A unique identifier for the named Conference.
</ParamField>

<ParamField path="Duration" type="integer">
  The time, in seconds, of the conference call.
</ParamField>

<ParamField path="EndConferenceOnExit" type="string">
  When a participant has this set on **true** and they leave a call, conference ends.
</ParamField>

<ParamField path="EventName" type="string">
  The name of the event.
</ParamField>

<ParamField path="FriendlyName" type="string">
  Name of the conference.
</ParamField>

<ParamField path="Hold" type="string">
  Whether a participant is on hold or not.
</ParamField>

<ParamField path="Muted" type="string">
  Whether a participant is muted or not.
</ParamField>

<ParamField path="RecordingFileSize" type="string">
  The size of the recorded audio file.
</ParamField>

<ParamField path="RecordingUrl" type="string">
  The URL of the recorded audio file.
</ParamField>

<ParamField path="StartConferenceOnEnter" type="string">
  When a participant has this set on **true** and they join a call, conference begins.
</ParamField>

<ParamField path="StatusCallbackEvent" type="string">
  Conference 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`.
</ParamField>

<ParamField path="Timestamp" type="string">
  The timestamp, in RFC 2822 format, of when an event occurred.
</ParamField>

#### Request parameters for the `recordingStatusCallback` URL  \[#conference\_recordingStatusCallback]

<WebhookPayloadSnippet webhook="recordingStatusCallback" />

#### Status values for the `recordingStatusCallbackEvent` attribute  \[#conference\_recordingStatusCallbackEvent]

The `recordingStatusCallbackEvent` attribute has the following status values:

| Value         | Description                                           |
| :------------ | :---------------------------------------------------- |
| `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

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference>Room 1234</Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference("Room 1234");
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  from signalwire.voice_response import VoiceResponse, Dial, Conference

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

  print(response)
  ```

  ```ruby
  require 'signalwire/sdk'

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

  puts response.to_s
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference startConferenceOnEnter="false">
        moderated-conference-room
      </Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference("moderated-conference-room", { startConferenceOnEnter: false });
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  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)
  ```

  ```ruby
  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
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
        moderated-conference-room
      </Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference("moderated-conference-room", {
    startConferenceOnEnter: true,
    endConferenceOnExit: true,
  });
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  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)
  ```

  ```ruby
  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
  ```
</CodeBlocks>

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)

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference muted="true">ConferenceRoom</Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference({ muted: true }, "ConferenceRoom");
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  from signalwire.voice_response import VoiceResponse, Dial, Conference

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

  print(response)
  ```

  ```ruby
  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
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <Response>
    <Dial>
      <Conference coach="AgentCallSid">
        Example-Room
      </Conference>
    </Dial>
  </Response>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  const response = new RestClient.LaML.VoiceResponse();

  dial = response.dial();
  dial.conference("Example-Room", { coach: "AgentCallSid" });
  console.log(response.toString());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  from signalwire.voice_response import VoiceResponse, Dial, Conference

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

  print(response)
  ```

  ```ruby
  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
  ```
</CodeBlocks>

### Recording a conference call

<CodeBlocks>
  ```xml
  <?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>
  ```

  ```javascript title="Node.js"
  const { RestClient } = require("@signalwire/compatibility-api");
  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());
  ```

  ```csharp
  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());;
      }
  }
  ```

  ```python
  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)
  ```

  ```ruby
  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
  ```
</CodeBlocks>

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.