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

# Conference calls in the Vobiz Flutter SDK

> Turn a call into a conference with VobizConference: dial people in, mute, hold, resume, or remove participants, end the conference for everyone, and implement the four server routes it calls.

`VobizConference` turns the current call into a conference: you dial more people in and manage them while you stay on the call. Vobiz mixes the audio in a [conference room](https://www.vobiz.ai/docs/xml/conference.md).

## How it works

Moving a call into a room, dialling people, and muting them are Vobiz REST API calls that need your account Auth Token, which must never be in the app. So `VobizConference` asks **your server**, and your server makes those calls. Your server implements four routes (see [Server routes](#server-routes)).

1. The first `add` moves both sides of the call into a new room, with the [Transfer API](https://www.vobiz.ai/docs/call/transfer-call.md), and dials the new person into it with the [Call API](https://www.vobiz.ai/docs/call/make-call.md).
2. Later `add` calls only dial.
3. While the conference is on, the class polls your server for the state and exposes it as a `ValueListenable`.
4. When the conference ends, the class hangs up the call.

## Create a conference

```dart Signature theme={null}
VobizConference({
  required VobizClient client,
  required Uri serverUrl,
  FutureOr<Map<String, String>> Function()? headers,
  String? Function()? callUuid,
  http.Client? httpClient,
  Duration pollInterval = const Duration(seconds: 2),
  Duration timeout = const Duration(seconds: 15),
  bool endCallWithConference = true,
})
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `client` | `VobizClient` | Required | The signed-in client with the call. |
| `serverUrl` | `Uri` | Required | The base URL of the server that implements the conference routes. Use HTTPS. |
| `headers` | `FutureOr<Map<String, String>> Function()?` | `null` | Headers for each request, such as your app's session token. |
| `callUuid` | `String? Function()?` | `client.callUuid` | The CallUUID that identifies the call to your server. |
| `httpClient` | `http.Client?` | A client the class creates | The HTTP client. |
| `pollInterval` | `Duration` | 2 seconds | How often the state is refreshed while the conference is on. |
| `timeout` | `Duration` | 15 seconds | The timeout for each request. |
| `endCallWithConference` | `bool` | `true` | Hang up the call when the conference ends. |

Call `dispose()` when you no longer need the object.

## Add people

```dart Signature theme={null}
Future<VobizConferenceState> add({String? number, String? sipUser, String? callerId})
```

| Parameter | Type | Description |
| - | - | - |
| `number` | `String?` | A phone number in E.164 format. Give this or `sipUser`. |
| `sipUser` | `String?` | A SIP endpoint username. |
| `callerId` | `String?` | The number the dialled person sees. It must be one of your Vobiz numbers. Without it, your server picks one. |

**Returns** the conference state. **Throws** `StateError` when there is no answered call (a held call is refused), `ArgumentError` for a malformed target, and `VobizException` (`conference_failed`) when your server refuses.

```dart theme={null}
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

Future<VobizConference> startConference(VobizClient client) async {
  final conference = VobizConference(
    client: client,
    serverUrl: Uri.parse('https://api.example.com'),
    headers: () async => {'Authorization': 'Bearer YOUR_APP_SESSION_TOKEN'},
  );
  await conference.add(number: '+91XXXXXXXXXX', callerId: '+91YYYYYYYYYY');
  return conference;
}
```

## Manage participants

```dart Signature theme={null}
Future<VobizConferenceState> mute(String participantId)
Future<VobizConferenceState> unmute(String participantId)
Future<VobizConferenceState> hold(String participantId)
Future<VobizConferenceState> resume(String participantId)
Future<VobizConferenceState> remove(String participantId)
Future<VobizConferenceState> act(String participantId, VobizParticipantAction action)
```

| Method | Effect |
| - | - |
| `mute` | The others stop hearing this person. |
| `unmute` | The others hear them again. |
| `hold` | Takes them out of the room onto hold music: they hear nobody and nobody hears them. |
| `resume` | Brings them back into the room. |
| `remove` | Hangs up their leg. |
| `act` | The same actions by `VobizParticipantAction` value. |

These act on the participant for everyone in the room. To mute your own microphone, use `client.mute()`.

## Read the state

```dart Signature theme={null}
ValueListenable<VobizConferenceState?> get state
Future<VobizConferenceState?> refresh()
Future<VobizConferenceState> end()
```

`state` is `null` until the call is a conference, and goes back to `null` when the call ends. `refresh()` fetches the state now and returns `null` when your server says the call isn't a conference. `end()` ends the conference for everyone and hangs up this call.

| `VobizConferenceState` member | Description |
| - | - |
| `room` | The conference room's name. |
| `active` | `false` once the conference has ended. |
| `participants` | Everyone who joined, including people who left. |
| `present` | The people still in the conference (`isPresent`), this app included. |
| `endedReason` | Why the conference ended, when it has. |

| `VobizConferenceParticipant` member | Description |
| - | - |
| `id` | Your server's ID for this person. Pass it to the participant methods. |
| `label` | A name or number to show. |
| `status` | A `VobizParticipantStatus`. |
| `isYou` | `true` for this app's own leg. |
| `role` | Your server's role for them, such as host. |
| `muted` | Whether the others can't hear them. |
| `reason` | Why they failed or left, when known. |
| `isPresent` | `true` while they are still in the conference: on the way in, being dialled, in the room, or on hold. |

| `VobizParticipantStatus` | Meaning |
| - | - |
| `connecting` | Moving into the room: the call's own two sides just after it became a conference, someone who just answered, or someone coming back from hold. |
| `dialing` | Being dialled. |
| `joined` | In the room. |
| `onHold` | On hold music, outside the room. |
| `left` | Hung up, was removed, or the conference ended. |
| `failed` | Didn't answer, was busy, or couldn't be dialled. |

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

class ParticipantList extends StatelessWidget {
  const ParticipantList({super.key, required this.conference});

  final VobizConference conference;

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder<VobizConferenceState?>(
      valueListenable: conference.state,
      builder: (context, state, _) {
        if (state == null) return const Text('Not a conference');
        return Column(
          children: [
            for (final person in state.present)
              ListTile(
                title: Text(person.isYou ? 'You' : person.label),
                subtitle: Text(person.status.name),
                trailing: person.isYou
                    ? null
                    : IconButton(
                        icon: Icon(person.muted ? Icons.mic_off : Icons.mic),
                        onPressed: () => person.muted
                            ? conference.unmute(person.id)
                            : conference.mute(person.id),
                      ),
              ),
          ],
        );
      },
    );
  }
}
```

## Server routes

Your server implements four JSON `POST` routes under `serverUrl`. Each answers with the conference state, and authenticates the app with the headers you pass.

| Route | Request body | What your server does |
| - | - | - |
| `POST /conference/add` | `call_uuid`, `number` or `user`, optional `caller_id` | The first time, moves both legs of the call into a new room with the Transfer API. Then dials the person into the room with the Call API. |
| `POST /conference/state` | `call_uuid` | Returns the current state, or `404` when the call isn't a conference. |
| `POST /conference/participant` | `call_uuid`, `participant_id`, `action` (`mute`, `unmute`, `hold`, `resume`, or `remove`) | Applies the action with the conference member APIs, or moves the leg to hold music and back. |
| `POST /conference/end` | `call_uuid` | Ends the room for everyone. |

Every route returns:

```json theme={null}
{
  "room": "ROOM_NAME",
  "active": true,
  "participants": [
    { "id": "p1", "label": "You", "status": "joined", "you": true, "role": "host", "muted": false },
    { "id": "p2", "label": "+91XXXXXXXXXX", "status": "dialing", "you": false, "role": "guest", "muted": false }
  ]
}
```

`status` is one of `connecting`, `dialing`, `joined`, `on_hold`, `left`, or `failed`. When the conference has ended, return `"active": false` and an optional `"ended_reason"`. An error reply is `{"error": "...", "conference": { ...state }}`; the state in it, if present, is still applied.

The SDK's example app includes a reference implementation of these routes in its push bridge (`example/push_bridge`). It also ends the room about 2 seconds after the host's app stops reporting, so a host who loses the network doesn't leave the others in an empty call.

## Next steps

* [In-call controls](https://www.vobiz.ai/docs/integrations/flutter-sdk/in-call-controls.md)
* [`<Conference>` in VobizXML](https://www.vobiz.ai/docs/xml/conference)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.