> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-party Call

> Create role-based multi-party calls with coaching, recording controls, and AI agent integration

The `<MultiPartyCall>` element creates or joins a multi-party call (MPC) with advanced features like participant roles, coach mode for supervisors, and individual hold/mute controls.

<Info>
  For simple conference bridges without roles, see [Conference](/voice/xml/conference/).
</Info>

### Basic Usage

```xml theme={null}
<Response>
    <MultiPartyCall role="customer" maxDuration="10000">
        my-mpc-name
    </MultiPartyCall>
</Response>
```

<CodeGroup>
  ```python Python theme={null}
  from plivo import plivoxml

  response = plivoxml.ResponseElement()
  response.add(plivoxml.MultiPartyCallElement(
      content='my-mpc-name',
      role='customer',
      max_duration=10000
  ))
  print(response.to_string())
  ```

  ```javascript Node.js theme={null}
  const plivo = require('plivo');

  const response = plivo.Response();
  response.addMultiPartyCall('my-mpc-name', {
      role: 'customer',
      maxDuration: 10000
  });
  console.log(response.toXML());
  ```

  ```ruby Ruby theme={null}
  require 'plivo'

  response = Plivo::XML::Response.new
  response.addMultiPartyCall('my-mpc-name',
      role: 'Agent',
      maxDuration: 10000)
  puts Plivo::XML::PlivoXML.new(response).to_xml
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';
  use Plivo\XML\Response;

  $response = new Response();
  $response->addMultiPartyCall('my-mpc-name', [
      'role' => 'Customer',
      'maxDuration' => 10000
  ]);
  echo $response->toXML();
  ```

  ```java Java theme={null}
  import com.plivo.api.xml.*;
  import com.plivo.api.models.multipartycall.MultiPartyCallUtils;

  Response response = new Response();
  response.children(new MultiPartyCall("my-mpc-name", MultiPartyCallUtils.customer)
      .maxDuration(10000));
  System.out.println(response.toXmlString());
  ```

  ```csharp .NET theme={null}
  using Plivo.XML;

  var response = new Response();
  response.AddMultiPartyCall("my-mpc-name", new Dictionary<string, string>() {
      {"role", "customer"},
      {"maxDuration", "10000"}
  });
  Console.WriteLine(response.ToString());
  ```

  ```go Go theme={null}
  package main

  import "github.com/plivo/plivo-go/v7/xml"

  func main() {
      response := xml.ResponseElement{
          Contents: []interface{}{
              new(xml.MultiPartyCallElement).
                  SetRole("customer").
                  SetMaxDuration(10000).
                  SetContents("my-mpc-name"),
          },
      }
      print(response.String())
  }
  ```
</CodeGroup>

***

## Participant Roles

| Role         | Description                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `Customer`   | The customer being served                                                                                  |
| `Agent`      | Customer service representative                                                                            |
| `Supervisor` | Can monitor/coach agents (coach mode)                                                                      |
| `ai-agent`   | AI agent connected via WebSocket streaming (see [AI Agent Stream Attributes](#ai-agent-stream-attributes)) |

***

## MPC-Level Attributes

These settings apply to the entire multi-party call:

| Attribute                   | Type    | Default | Description                                                                                                                       |
| --------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `maxDuration`               | integer | `14400` | Max MPC duration in seconds (300-28800)                                                                                           |
| `maxParticipants`           | integer | `10`    | Maximum participants (2-10)                                                                                                       |
| `record`                    | boolean | `false` | Record the MPC                                                                                                                    |
| `recordFileFormat`          | string  | `mp3`   | Recording format (`mp3`, `wav`)                                                                                                   |
| `recordMinMemberCount`      | integer | `1`     | Min members to start recording (1 or 2)                                                                                           |
| `waitForAgent`              | boolean | `false` | When `true`, the MPC waits for an agent to join before starting. Customer participants hear wait music until an agent arrives     |
| `recordCoachVoice`          | boolean | -       | When `true`, includes the supervisor/coach voice in the call recording. When `false`, only agent and customer voices are recorded |
| `startRecordingAudio`       | URL     | -       | URL to fetch XML instructions for audio to play when recording starts                                                             |
| `startRecordingAudioMethod` | string  | `GET`   | HTTP method for `startRecordingAudio` URL. Values: `GET`, `POST`                                                                  |
| `stopRecordingAudio`        | URL     | -       | URL to fetch XML instructions for audio to play when recording stops                                                              |
| `stopRecordingAudioMethod`  | string  | `GET`   | HTTP method for `stopRecordingAudio` URL. Values: `GET`, `POST`                                                                   |

### Hold Music

| Attribute                 | Type   | Description                                     |
| ------------------------- | ------ | ----------------------------------------------- |
| `waitMusicUrl`            | URL    | Music for participants waiting for MPC to start |
| `waitMusicMethod`         | string | HTTP method for waitMusicUrl                    |
| `agentHoldMusicUrl`       | URL    | Music for agents on hold                        |
| `agentHoldMusicMethod`    | string | HTTP method for agent hold music                |
| `customerHoldMusicUrl`    | URL    | Music for customers on hold                     |
| `customerHoldMusicMethod` | string | HTTP method for customer hold music             |

### Callbacks

| Attribute                 | Type   | Description                        |
| ------------------------- | ------ | ---------------------------------- |
| `statusCallbackUrl`       | URL    | URL for MPC events                 |
| `statusCallbackMethod`    | string | HTTP method (`GET`, `POST`)        |
| `statusCallbackEvents`    | string | Events to receive (see below)      |
| `recordingCallbackUrl`    | URL    | URL for recording events           |
| `recordingCallbackMethod` | string | HTTP method for recording callback |

***

## Participant-Level Attributes

These settings apply to individual participants:

| Attribute         | Type    | Default    | Description                              |
| ----------------- | ------- | ---------- | ---------------------------------------- |
| `role`            | string  | *required* | `Agent`, `Supervisor`, or `Customer`     |
| `mute`            | boolean | `false`    | Join muted                               |
| `hold`            | boolean | `false`    | Join on hold                             |
| `coachMode`       | boolean | `true`     | Supervisor coach mode (supervisors only) |
| `stayAlone`       | boolean | `false`    | Stay if only participant                 |
| `startMpcOnEnter` | boolean | `true`     | Start MPC when joining                   |
| `endMpcOnExit`    | boolean | `false`    | End MPC when leaving                     |

### Entry/Exit Sounds

| Attribute          | Type   | Default  | Description                                        |
| ------------------ | ------ | -------- | -------------------------------------------------- |
| `enterSound`       | string | `beep:1` | Sound on entry: `none`, `beep:1`, `beep:2`, or URL |
| `enterSoundMethod` | string | `GET`    | HTTP method for enterSound URL                     |
| `exitSound`        | string | `beep:2` | Sound on exit: `none`, `beep:1`, `beep:2`, or URL  |
| `exitSoundMethod`  | string | `GET`    | HTTP method for exitSound URL                      |

### Actions

| Attribute            | Type    | Description                         |
| -------------------- | ------- | ----------------------------------- |
| `onExitActionUrl`    | URL     | URL called when participant exits   |
| `onExitActionMethod` | string  | HTTP method (`GET`, `POST`)         |
| `relayDTMFInputs`    | boolean | Transmit DTMF to other participants |

### AI Agent Stream Attributes

When `role` is set to `ai-agent`, use these attributes to connect an AI agent via WebSocket streaming.

| Attribute                           | Type   | Default                 | Description                                                         |
| ----------------------------------- | ------ | ----------------------- | ------------------------------------------------------------------- |
| `aiAgentStreamServiceUrl`           | URL    | -                       | WebSocket URL for the AI agent audio stream service                 |
| `aiAgentStreamContentType`          | string | `audio/x-l16;rate=8000` | Audio content type for the AI agent stream                          |
| `aiAgentStreamStatusCallbackUrl`    | URL    | -                       | URL for receiving AI agent stream status event callbacks            |
| `aiAgentStreamStatusCallbackMethod` | string | `POST`                  | HTTP method for the AI agent status callback. Values: `GET`, `POST` |
| `aiAgentStreamSamplingRate`         | string | -                       | Audio sampling rate for the AI agent stream                         |
| `aiAgentStreamExtraHeaders`         | object | `{}`                    | Custom headers sent with the AI agent WebSocket connection          |

***

## Examples

### Supervisor Coach Mode

Supervisors with `coachMode="true"` can hear everyone but only agents hear them (customers cannot):

**Supervisor joining:**

```xml theme={null}
<Response>
    <MultiPartyCall role="Supervisor" coachMode="true">
        support-call-123
    </MultiPartyCall>
</Response>
```

**Agent joining:**

```xml theme={null}
<Response>
    <MultiPartyCall role="Agent" startMpcOnEnter="true">
        support-call-123
    </MultiPartyCall>
</Response>
```

**Customer joining:**

```xml theme={null}
<Response>
    <MultiPartyCall role="Customer">
        support-call-123
    </MultiPartyCall>
</Response>
```

### MPC Recording

```xml theme={null}
<Response>
    <MultiPartyCall
        role="Agent"
        record="true"
        recordFileFormat="mp3"
        recordingCallbackUrl="https://example.com/recording-ready/">
        recorded-call
    </MultiPartyCall>
</Response>
```

#### Recording Events

* `MPCRecordingInitiated`
* `MPCRecordingPaused`
* `MPCRecordingResumed`
* `MPCRecordingCompleted`
* `MPCRecordingFailed`

### On Exit Action

Continue call flow after leaving MPC:

```xml theme={null}
<Response>
    <MultiPartyCall
        role="Customer"
        onExitActionUrl="https://example.com/post-call-survey/"
        onExitActionMethod="POST">
        support-call
    </MultiPartyCall>
</Response>
```

### Custom Hold Music

```xml theme={null}
<Response>
    <MultiPartyCall
        role="Agent"
        agentHoldMusicUrl="https://example.com/agent-hold.xml"
        customerHoldMusicUrl="https://example.com/customer-hold.xml"
        waitMusicUrl="https://example.com/wait-music.xml">
        call-center-mpc
    </MultiPartyCall>
</Response>
```

Hold music URLs must return XML with `Play`, `Speak`, or `Wait` elements.

***

## Status Callback Events

Configure which events to receive with `statusCallbackEvents`:

| Value                            | Events Included                                                                                                                                               |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mpc-state-changes`              | MPCInitialized, MPCStart, MPCEnd                                                                                                                              |
| `participant-state-changes`      | ParticipantJoin, ParticipantExit, ParticipantMute, ParticipantUnmute, ParticipantHold, ParticipantUnhold, ParticipantCoachModeStart, ParticipantCoachModeStop |
| `participant-speak-events`       | ParticipantSpeakStart, ParticipantSpeakStop                                                                                                                   |
| `participant-digit-input-events` | ParticipantDigitInput                                                                                                                                         |
| `add-participant-api-events`     | AddParticipantByAPIActionInitiated, AddParticipantByAPIActionCompleted                                                                                        |
| `participant-audio-events`       | ParticipantAudioStart, ParticipantAudioStop — triggered when audio from a participant starts or stops                                                         |

```xml theme={null}
<MultiPartyCall
    statusCallbackUrl="https://example.com/mpc-events/"
    statusCallbackEvents="mpc-state-changes,participant-state-changes,participant-speak-events">
    my-mpc
</MultiPartyCall>
```

### Status Callback Parameters

| Parameter              | Description                    |
| ---------------------- | ------------------------------ |
| `EventName`            | Event that triggered callback  |
| `EventTimestamp`       | When the event occurred        |
| `MPCUUID`              | Unique MPC identifier          |
| `MPCName`              | Friendly MPC name              |
| `MemberID`             | Participant identifier         |
| `ParticipantRole`      | Agent, Supervisor, or Customer |
| `ParticipantCallUUID`  | Participant's call UUID        |
| `ParticipantCoachMode` | Whether in coach mode          |
| `MPCDuration`          | Total MPC duration (on end)    |
| `MPCBilledDuration`    | Billed duration                |
| `MPCBilledAmount`      | Cost in USD                    |

### On Exit Parameters

| Parameter             | Description             |
| --------------------- | ----------------------- |
| `MPCUUID`             | MPC identifier          |
| `MPCFriendlyName`     | MPC name                |
| `MemberID`            | Participant ID          |
| `ParticipantCallUUID` | Call UUID               |
| `ParticipantJoinTime` | When participant joined |
| `ParticipantEndTime`  | When participant left   |
| `ParticipantRole`     | Participant's role      |

***

## Conference vs Multi-party Call

| Feature              | Conference      | Multi-party Call                            |
| -------------------- | --------------- | ------------------------------------------- |
| Max participants     | 20              | 10                                          |
| Participant roles    | No              | Yes (Agent, Customer, Supervisor, AI Agent) |
| Coach mode           | No              | Yes                                         |
| Individual hold/mute | No              | Yes                                         |
| API control          | Limited         | Full                                        |
| Use case             | Simple meetings | Call centers, support                       |

***

## Related

* [Conference](/voice/xml/conference/) — Simple conference bridge
* [Recording](/voice/xml/record/) — Record calls
* [Call Routing](/voice/xml/routing/) — Dial, Redirect, Hangup
* [Multi-party Call API](/voice/api/multiparty-calls/) — Control MPCs via API