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

# In-call controls in the Vobiz Flutter SDK

> Mute and unmute, switch between earpiece, speaker, Bluetooth, and wired headsets, put calls on hold, send DTMF, handle interruptions from other calls, and use the demo-only transfer and recordings in the Vobiz Flutter SDK.

These controls act on the current call. Each change is also reported as a typed event on `callMediaEvents` (see [Events and states](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md#media-events)).

## Mute

```dart Signature theme={null}
Future<void> mute([String? callId])
Future<void> unmute([String? callId])
bool get isMuted
```

Stops or resumes sending your microphone. Mute applies to the current call (`callId` is accepted for symmetry and ignored). Muting while a call is still connecting takes effect as soon as the microphone opens, and the mute survives hold and resume. Each new call starts unmuted. Every change emits a `MuteChangedEvent`.

```dart theme={null}
Future<void> toggleMute(VobizClient client) async {
  if (client.isMuted) {
    await client.unmute();
  } else {
    await client.mute();
  }
}
```

## Speakerphone

```dart Signature theme={null}
Future<void> setSpeakerphone(bool enabled)
bool get isSpeakerOn
```

`true` routes call audio to the loudspeaker; `false` routes it back to the earpiece or a connected headset. Each call starts off the loudspeaker.

```dart theme={null}
await client.setSpeakerphone(true);
```

## Audio routes

`client.audioRoutes` is an `AudioRouteController` that also handles Bluetooth and wired headsets.

| `AudioRoute` | Output |
| - | - |
| `earpiece` | The phone's receiver, held to the ear. |
| `speaker` | The loudspeaker. |
| `bluetooth` | A Bluetooth headset or car kit. |
| `wiredHeadset` | A wired headset or USB headphones. |

| Member | Description |
| - | - |
| `Future<List<AudioRoute>> availableRoutes()` | The routes available right now. |
| `Future<List<AudioRouteDevice>> availableDevices()` | The output devices the platform reports, each mapped to a route. |
| `Future<void> selectRoute(AudioRoute route)` | Moves call audio to `route`. |
| `Future<void> setSpeakerOn(bool enabled)` | The same as `client.setSpeakerphone`. |
| `AudioRoute get currentRoute` | The route the SDK last selected. |
| `bool get isSpeakerOn` | Whether audio is on the loudspeaker. |
| `Stream<AudioRoute> get routeChanges` | Emits each time the route changes. Route changes also arrive as `AudioRouteChangedEvent` on `callMediaEvents`. |
| `Future<bool> ensureBluetoothPermission()` | Asks for Bluetooth permission once per app run, through the requester you supply. |

After the last call ends, the SDK resets the route to the earpiece, so a speaker choice doesn't leak into the next call.

On Android 12 and later, routing to a Bluetooth headset needs the `BLUETOOTH_CONNECT` runtime permission. The SDK doesn't depend on a permission plugin; ask for it with the plugin you already use before you select `AudioRoute.bluetooth`.

```dart theme={null}
Future<void> useHeadsetIfAvailable(VobizClient client) async {
  final routes = await client.audioRoutes.availableRoutes();
  if (routes.contains(AudioRoute.bluetooth)) {
    await client.audioRoutes.selectRoute(AudioRoute.bluetooth);
  }
}
```

## Hold and resume

```dart Signature theme={null}
Future<void> hold([String? callId])
Future<void> resume([String? callId])
```

`hold()` puts the connected call on hold with a SIP re-INVITE offering `a=sendonly`, so the other party hears hold music instead of silence. Your microphone is silenced while the call is held. `resume()` sends `a=sendrecv` and brings the call back; the microphone stays muted if you had muted it.

`callEvents` reports `held` and then `active`, and `callMediaEvents` emits `HoldChangedEvent`.

**Throws** `StateError` when there is no connected call (for `hold()`) or the call isn't on hold (for `resume()`), and `VobizException` with code `hold_failed` or `resume_failed` when the far end refuses. The call then carries on as it was. Only one hold or resume can be in progress at a time.

```dart theme={null}
Future<void> toggleHold(VobizClient client) async {
  try {
    if (client.callState == CallStateStatus.held) {
      await client.resume();
    } else {
      await client.hold();
    }
  } on VobizException catch (e) {
    debugPrint('Hold change refused (${e.code}): ${e.message}');
  }
}
```

## DTMF

```dart Signature theme={null}
Future<void> sendDtmf(
  String digits, {
  DtmfTransport transport = DtmfTransport.auto,
})
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `digits` | `String` | Required | One or more of `0`-`9`, `*`, `#`, and `A`-`D`, such as `'1234#'`. |
| `transport` | `DtmfTransport` | `auto` | How the tones are sent. |

| `DtmfTransport` | Behaviour |
| - | - |
| `auto` | RFC 4733 telephone-events in the audio when the call negotiated `telephone-event`, otherwise SIP INFO. |
| `rfc4733` | RFC 4733 only. Throws `StateError` when the call didn't negotiate `telephone-event`. |
| `sipInfo` | SIP INFO (`application/dtmf-relay`), one digit at a time, 500 ms apart. |

**Throws** `ArgumentError` for any other character, and `StateError` when the call isn't connected. A held call is refused.

```dart theme={null}
// Answer an IVR menu: press 1, then enter an account number.
await client.sendDtmf('1');
await client.sendDtmf('12345678#');
```

## Interruptions from other calls

The SDK can't detect when another app's call, such as a cellular or WhatsApp call, takes the microphone. Tell it, and it holds the Vobiz call so the other party hears hold music instead of silence:

```dart Signature theme={null}
Future<void> audioInterruptionBegan()
Future<void> audioInterruptionEnded({bool shouldResume = true})
```

`audioInterruptionEnded` resumes the call if `audioInterruptionBegan` held it and `shouldResume` is `true`. A call the user held stays held. Feed it from your audio-session plugin, for example `package:audio_session`, which reports Android audio-focus loss and iOS `AVAudioSession` interruptions:

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

Future<void> holdOnInterruptions(VobizClient client) async {
  final session = await AudioSession.instance;
  session.interruptionEventStream.listen((event) {
    if (event.begin) {
      client.audioInterruptionBegan();
    } else {
      client.audioInterruptionEnded();
    }
  });
}
```

## Transfer a call (demo mode)

> [!WARNING]
>
> Transfers work only after signing in with [Zero-Config](https://www.vobiz.ai/docs/integrations/flutter-sdk/sign-in.md#demo-mode-zero-config), because the transfer is made with your account Auth ID and Auth Token through the webhook server. Don't use it in a shipped app. In production, transfer from your server with the [Transfer API](https://www.vobiz.ai/docs/call/transfer-call.md), using the call's `callUuid`.

```dart Signature theme={null}
Future<String> transferCall({
  String? number,
  String? sipUser,
  TransferLeg leg = TransferLeg.aLeg,
  String? callerId,
  Map<String, String> sipHeaders = const <String, String>{},
})
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `number` | `String?` | `null` | A phone number in E.164 format. Give this or `sipUser`, not both. |
| `sipUser` | `String?` | `null` | A SIP endpoint username to transfer to. |
| `leg` | `TransferLeg` | `aLeg` | Which side moves. |
| `callerId` | `String?` | `null` | The caller ID for the new `<Dial>`. |
| `sipHeaders` | `Map<String, String>` | `{}` | `X-VH-` headers to carry on the new `<Dial>`. Names that contain characters other than letters and digits are dropped. |

| `TransferLeg` | Effect |
| - | - |
| `aLeg` | Moves your own side onto the target. The other party is dropped. |
| `bLeg` | Moves the other party onto the target. Your side is dropped. |
| `both` | Each side runs the transfer on its own, for example both join a conference. |

**Returns** the server's confirmation. **Throws** `StateError` when the call isn't answered, when not signed in with Zero-Config, or before Vobiz has reported the CallUUID; `ArgumentError` for a bad target or header; and `VobizException` (`transfer_failed`) when the server refuses.

## Recordings (demo mode)

`makeCall(record: true)` asks your Answer URL to record the call. With Zero-Config, the hosted webhook server records it and lists the file:

```dart Signature theme={null}
Future<List<VobizRecording>> fetchRecordings()
Future<VobizRecording?> waitForRecording(
  String callUuid, {
  Duration interval = const Duration(milliseconds: 2500),
  int attempts = 12,
})
```

`waitForRecording` polls every `interval`, up to `attempts` times, for the recording of the call with `callUuid` (usually `client.lastCallUuid`), and returns `null` if it never arrives. A `VobizRecording` has `recordingId`, `callUuid`, `url`, `durationSecs`, `endReason`, and `receivedAt`.

On the shared demo server the list is visible to everyone who uses it, so the SDK reads it only with `SdkConfig(unsafeDemoZeroConfig: true)`. In production, receive recordings on your own server with the [recording callback](https://www.vobiz.ai/docs/xml/record.md) of your Answer URL's VobizXML.

## Proximity sensor

`client.proximity` accepts a `ProximityController` that turns the screen off when the phone is held to the ear during an earpiece call. The SDK provides the hook; supply the platform code from your app. The default, `NoProximityController`, does nothing.

## Next steps

* [Custom SIP headers](https://www.vobiz.ai/docs/integrations/flutter-sdk/sip-headers.md)
* [Call quality](https://www.vobiz.ai/docs/integrations/flutter-sdk/call-quality.md)
* [Events and states](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md)


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