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

# Network changes and reconnection in the Vobiz Flutter SDK

> How the Vobiz Flutter SDK keeps the app reachable and calls alive: automatic reconnection with ReconnectPolicy, keep-alive, network-change detection, foreground re-registration, call recovery after a network drop, and STUN, TURN, and microphone settings.

Phones change networks all the time: Wi-Fi to mobile data, tunnels, lifts, a locked screen. The SDK handles these for you with sensible defaults. This page explains what it does and how to tune it.

## What happens by default

| Situation | What the SDK does |
| - | - |
| The connection drops while idle | Reconnects and re-registers, with backoff from 1 to 30 seconds, up to 10 attempts. |
| The device goes offline | Stops trying, fails new calls immediately, and reconnects as soon as a network is back. |
| The device switches network, such as Wi-Fi to mobile | Replaces the connection at once when idle. During a call, it keeps the old connection until it stops working, then reconnects. |
| The app returns to the foreground | Registers again, so Vobiz has the device's current address. |
| A refresh of the registration goes unanswered | Treats the connection as dead and reconnects at once. |
| The network drops during a call | Keeps the call for up to 12 seconds while it reconnects, then restores the audio. |
| A hang-up couldn't be sent because the network was down | Sends the `BYE` or `CANCEL` again once it reconnects. |

`networkEvents` reports each step. See [Network events](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md#network-events).

## Reconnect policy

```dart Signature theme={null}
const ReconnectPolicy({
  Duration initialDelay = const Duration(seconds: 1),
  Duration maxDelay = const Duration(seconds: 30),
  double multiplier = 2.0,
  int? maxAttempts = 10,
  double jitter = 0.2,
})
```

| Field | Default | Description |
| - | - | - |
| `initialDelay` | 1 second | Wait before the first attempt. |
| `maxDelay` | 30 seconds | The longest wait between attempts. |
| `multiplier` | `2.0` | Each wait is the previous one times this, up to `maxDelay`. |
| `maxAttempts` | `10` | Attempts before giving up with `reconnect_failed`. `null` never gives up. |
| `jitter` | `0.2` | Randomises each wait by up to ±20%, so many devices don't reconnect at the same instant. |

Each attempt must be registered within 10 seconds, or it counts as failed. After giving up, `connectionState` is `failed` and `errorEvents` emits `reconnect_failed`. The SDK tries again on the next network change, or when you call `client.reconnect()`, for example from a **Retry** button.

```dart theme={null}
final client = VobizClient(
  config: const SdkConfig(
    reconnectPolicy: ReconnectPolicy(maxAttempts: null),
  ),
);
```

Set `SdkConfig(autoReconnect: false)` to handle reconnection yourself.

## Keep-alive

```dart Signature theme={null}
const KeepAliveConfig({
  Duration? pingInterval = const Duration(seconds: 15),
  Duration? crlfInterval,
  Duration crlfPongTimeout = const Duration(seconds: 10),
})
```

| Field | Default | Description |
| - | - | - |
| `pingInterval` | 15 seconds | Sends a WebSocket ping at this interval. A connection that stops answering is noticed within about two intervals. `null` turns it off. |
| `crlfInterval` | `null` (off) | Also sends a SIP double-CRLF keep-alive (RFC 5626) at this interval. |
| `crlfPongTimeout` | 10 seconds | How long to wait for the CRLF reply before treating the connection as dead. |

## Network watching and foreground re-registration

* `SdkConfig.watchNetwork` (default `true`) watches Wi-Fi, mobile, and offline through `connectivity_plus`, so the SDK reacts at once instead of waiting for the keep-alive.
* `SdkConfig.reregisterOnForeground` (default `true`) registers again each time the app returns to the foreground. On a live connection this is one REGISTER on the same connection, and a call in progress isn't touched. A dead connection is reconnected at once. Resumes within 2 seconds of each other count as one.

## Calls during a network drop

When the connection drops during a connected or held call:

1. The call stays up for up to **12 seconds**. `callEvents` re-emits the call's state with `reason: 'reconnecting'`.
2. The SDK reconnects and re-registers. Once it is registered, it restarts the call's audio path on the new network (an ICE restart in a SIP re-INVITE) and emits the state again with `reason: 'reconnected'`.
3. If the network isn't back within 12 seconds, the call ends with reason `network_lost`.

A call that is still being set up when the network drops ends at once. While the device is offline, `makeCall` throws `StateError('No network connection')`.

```dart theme={null}
void showReconnecting(VobizClient client) {
  client.callEvents.listen((event) {
    if (event.reason == 'reconnecting') debugPrint('Reconnecting the call...');
    if (event.reason == 'reconnected') debugPrint('Call restored');
  });
}
```

If you hang up while the network is down, the `BYE` or `CANCEL` is sent again after the SDK reconnects: up to 3 times, within 5 minutes, as the same user. The other side isn't left on a silent call.

> [!NOTE]
>
> An outage longer than 12 seconds ends the call on the app side, and the `BYE` follows when the app reconnects. If the app never reconnects, Vobiz ends the call on its side after a media timeout.

## STUN and TURN

Call audio uses WebRTC, which needs to find a network path to Vobiz's media servers. By default the SDK uses Google's public STUN server, which works on most networks. Behind strict corporate firewalls or symmetric NAT, add your own TURN server.

```dart Signature theme={null}
const IceConfig({
  List<IceServerConfig> servers = const [IceServerConfig(urls: ['stun:stun.l.google.com:19302'])],
  IceTransportPolicy iceTransportPolicy = IceTransportPolicy.all,
})

const IceServerConfig({
  required List<String> urls,
  String? username,
  String? credential,
})
```

| `IceTransportPolicy` | Effect |
| - | - |
| `all` | Use any path: direct, STUN, or TURN. |
| `relay` | Use TURN relays only. |

`TurnServers.withFallbacks` builds the TURN entries for UDP, TCP, and TLS on port 443 in one call, so calls also work on networks that block everything but HTTPS:

```dart Signature theme={null}
static List<IceServerConfig> TurnServers.withFallbacks({
  required String host,
  required String username,
  required String credential,
  int port = 3478,
  String? tlsHost,
  int tlsPort = 443,
  bool udp = true,
  bool tcp = true,
  bool tls = true,
})
```

```dart theme={null}
final client = VobizClient(
  config: SdkConfig(
    iceConfig: IceConfig(
      servers: [
        const IceServerConfig(urls: ['stun:stun.l.google.com:19302']),
        ...TurnServers.withFallbacks(
          host: 'turn.example.com',
          username: 'YOUR_TURN_USERNAME',
          credential: 'YOUR_TURN_PASSWORD',
        ),
      ],
    ),
  ),
);
```

Vobiz doesn't provide TURN servers: use your own or a TURN provider.

## Microphone settings

```dart Signature theme={null}
const MediaConstraints({
  bool audio = true,
  bool video = false,
  bool echoCancellation = true,
  bool noiseSuppression = true,
  bool autoGainControl = true,
  List<String> preferredAudioCodecs = const <String>[],
})
```

| Field | Default | Description |
| - | - | - |
| `echoCancellation` | `true` | Removes the far end's voice picked up from the speaker. |
| `noiseSuppression` | `true` | Reduces background noise on the device before sending. |
| `autoGainControl` | `true` | Evens out the microphone level. |
| `preferredAudioCodecs` | `[]` | Codec names to move to the front of the offer, such as `['PCMU']`. Empty keeps WebRTC's order. |
| `audio` / `video` | `true` / `false` | The SDK is audio-only; leave these as they are. |

## Next steps

* [Events and states](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md)
* [Push notifications](https://www.vobiz.ai/docs/integrations/flutter-sdk/push-notifications.md)


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