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

# Events and states in the Vobiz Flutter SDK

> Every Dart stream the Vobiz Flutter SDK emits (connection, call, media, network, error, and push events), their fields, the connection and registration states, and the client getters for the current state.

The client reports everything as broadcast `Stream`s. Listen to the ones you need, and cancel your subscriptions when the screen that owns them goes away.

## Streams

| Stream | Event type | Emits when |
| - | - | - |
| `connectionEvents` | `ConnectionEvent` | The connection or registration state changes. |
| `callEvents` | `CallEvent` | A call changes state. See [Call states](https://www.vobiz.ai/docs/integrations/flutter-sdk/calls.md#call-states). |
| `callMediaEvents` | `CallMediaEvent` | Mute, hold, early media, audio route, or call quality changes. |
| `networkEvents` | `NetworkEvent` | The device's network or the signalling connection changes. |
| `errorEvents` | `ErrorEvent` | Something failed. See [Errors](https://www.vobiz.ai/docs/integrations/flutter-sdk/errors.md). |
| `pushCallUpdates` | `VobizPushCallUpdate` | A pushed call moves on. See [Push notifications](https://www.vobiz.ai/docs/integrations/flutter-sdk/push-notifications.md#follow-the-pushed-call). |
| `mediaEvents` | `MediaEvent` | Low-level media events from WebRTC. Prefer `callMediaEvents`. |

Every event extends `SdkEvent` and has a `timestamp`.

```dart theme={null}
import 'dart:async';

import 'package:flutter/foundation.dart';
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

class CallListeners {
  CallListeners(this.client);

  final VobizClient client;
  final _subscriptions = <StreamSubscription<Object?>>[];

  void start() {
    _subscriptions
      ..add(client.connectionEvents.listen((e) => debugPrint('Connection: ${e.connectionState.name}')))
      ..add(client.callEvents.listen((e) => debugPrint('Call ${e.callId}: ${e.state.name}')))
      ..add(client.callMediaEvents.listen((e) => debugPrint('Media: $e')))
      ..add(client.errorEvents.listen((e) => debugPrint('Error ${e.code}: ${e.message}')));
  }

  Future<void> stop() async {
    for (final subscription in _subscriptions) {
      await subscription.cancel();
    }
    _subscriptions.clear();
  }
}
```

## Connection events

| `ConnectionEvent` field | Type | Description |
| - | - | - |
| `connectionState` | `ConnectionStateStatus` | The signalling connection's state. |
| `registrationState` | `RegistrationState` | The registration's state. |
| `message` | `String?` | What happened, in words. |

| `ConnectionStateStatus` | Meaning |
| - | - |
| `disconnected` | Signed out, or never signed in. |
| `connecting` | Opening the connection or registering. |
| `connected` | Connected. Calls are possible once `registrationState` is `registered`. |
| `reconnecting` | The connection dropped and the SDK is reconnecting. |
| `failed` | The connection failed. With `autoReconnect`, the SDK keeps trying until the [reconnect policy](https://www.vobiz.ai/docs/integrations/flutter-sdk/network.md#reconnect-policy) gives up. |

| `RegistrationState` | Meaning |
| - | - |
| `unregistered` | Not registered. |
| `registering` | A REGISTER is in flight. |
| `registered` | Vobiz accepted the registration: the app can call and be called. |
| `failed` | Vobiz refused the registration, for example wrong credentials or an expired token. |

## Call events

`CallEvent` fields and states are documented in [Make and receive calls](https://www.vobiz.ai/docs/integrations/flutter-sdk/calls.md#callevent).

## Media events

`CallMediaEvent` is a sealed class. Every subtype has a `callId` (`null` for a route change between calls).

| Subtype | Fields | Emits when |
| - | - | - |
| `MuteChangedEvent` | `bool muted` | The microphone is muted or unmuted, including when a new call starts unmuted. |
| `HoldChangedEvent` | `bool held` | The call is put on hold or resumed. |
| `EarlyMediaEvent` | | A `183 Session Progress` carried audio, such as ringback or a carrier announcement, and it is playing. |
| `AudioRouteChangedEvent` | `AudioRoute route` | Call audio moved to another output. |
| `CallQualityEvent` | `CallQualitySample sample`, `bool levelChanged`, `CallQualityLevel level` | A quality measurement, every 2 seconds once audio connects. See [Call quality](https://www.vobiz.ai/docs/integrations/flutter-sdk/call-quality.md). |

```dart theme={null}
void showMediaChanges(VobizClient client) {
  client.callMediaEvents.listen((event) {
    switch (event) {
      case MuteChangedEvent(:final muted):
        debugPrint(muted ? 'Muted' : 'Unmuted');
      case HoldChangedEvent(:final held):
        debugPrint(held ? 'On hold' : 'Resumed');
      case EarlyMediaEvent():
        debugPrint('Playing early media');
      case AudioRouteChangedEvent(:final route):
        debugPrint('Audio now on ${route.name}');
      case CallQualityEvent(:final levelChanged, :final level):
        if (levelChanged) debugPrint('Call quality is now ${level.name}');
    }
  });
}
```

## Network events

| `NetworkEvent` field | Type | Description |
| - | - | - |
| `type` | `NetworkEventType` | What happened. |
| `network` | `NetworkStatus` | The network at the time of the event. |
| `previousNetwork` | `NetworkStatus?` | The network before an `offline`, `online`, or `networkChanged` event. |
| `quality` | `SignalingQuality` | How usable the signalling connection is now. |
| `attempt` | `int` | The reconnect attempt number (from 1), or the number of attempts made for `reconnectFailed`. |
| `retryIn` | `Duration?` | When the next attempt runs, for a scheduled `reconnecting`. |
| `reason` | `String?` | Why, in words. |

| `NetworkEventType` | Meaning |
| - | - |
| `offline` | The device lost every network. Calls can't be placed until it is back. |
| `online` | The device has a network again. |
| `networkChanged` | The device moved to another network, such as Wi-Fi to mobile. The connection is replaced. |
| `reconnecting` | A reconnect attempt is scheduled or running. |
| `reconnected` | The connection is back and registered. |
| `reconnectFailed` | Reconnecting gave up. The SDK tries again on the next network change or when you call `client.reconnect()`. |

| `SignalingQuality` | Meaning |
| - | - |
| `good` | Connected and registered. |
| `degraded` | Reconnecting, or a network change isn't confirmed yet. Calls may fail. |
| `unavailable` | No network, or reconnecting has given up. |

`NetworkStatus.types` is the set of `NetworkType` values the device is on (`none`, `wifi`, `mobile`, `ethernet`, `vpn`, `other`).

## Error events

| `ErrorEvent` field | Type | Description |
| - | - | - |
| `code` | `String` | A stable code, such as `registration_failed`. See [Error codes](https://www.vobiz.ai/docs/integrations/flutter-sdk/errors.md#error-codes). |
| `message` | `String` | What happened, in words. |
| `cause` | `Object?` | The underlying exception, such as a `VobizAccessTokenException`. |

## Current state

Read the current state at any time without listening:

| Getter | Type | Description |
| - | - | - |
| `isConnected` | `bool` | Connected and registered. |
| `connectionState` | `ConnectionStateStatus` | See above. |
| `registrationState` | `RegistrationState` | See above. |
| `network` | `NetworkStatus?` | The device's network, once known. |
| `signalingQuality` | `SignalingQuality` | See above. |
| `authMode` | `VobizAuthMode` | How the client signed in. |
| `sipUsername` | `String?` | The registered identity. |
| `callState` | `CallStateStatus` | The current call's state, or `idle`. |
| `currentCallId` | `String?` | The current call's ID. |
| `callDirection` | `CallDirection?` | `inbound` or `outbound`. |
| `callUuid` / `lastCallUuid` | `String?` | Vobiz's CallUUID for the current call, and for the previous one. |
| `callHeaders` | `Map<String, String>` | The current call's `X-VH-` headers. |
| `currentCall` | `CallSession?` | The current call as an object, with its state and available actions. |
| `isMuted` / `isSpeakerOn` | `bool` | Microphone and speaker state. |
| `pushedCall` | `VobizIncomingPush?` | The push being handled, if any. |

## Next steps

* [Errors and troubleshooting](https://www.vobiz.ai/docs/integrations/flutter-sdk/errors.md)
* [Call quality](https://www.vobiz.ai/docs/integrations/flutter-sdk/call-quality.md)


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