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

> [!NOTE]
>
> For simple conference bridges without roles, see [Conference](https://plivo.com/docs/voice/xml/conference.md).

### Basic Usage

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

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

***

## 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](https://plivo.com/docs/voice/xml/conference.md) — Simple conference bridge
* [Recording](https://plivo.com/docs/voice/xml/record.md) — Record calls
* [Call Routing](https://plivo.com/docs/voice/xml/routing.md) — Dial, Redirect, Hangup
* [Multi-party Call API](https://plivo.com/docs/voice/api/multiparty-calls.md) — Control MPCs via API
* [Transfer to Human Agent](https://plivo.com/docs/voice/use-cases/transfer-to-human-agent/multiparty-call.md) — Hand a call from an `ai-agent` participant to a human agent, including warm transfer