Voice

import 'package:nexus_flutter/nexus.dart';

NexusVoiceCopy Anchor Link

Nexus Voice — the client calling API. Talks to the Voice control plane (/partner/voice/*), drives a pluggable NexusVoiceEngine for media and an optional NexusCallKit for the native call UI, and exposes the live call as a ValueListenable. Follows the SDK rule: it NEVER throws into the app — failures are logged and surface as a failed/ended call state.

currentCopy Anchor Link

final ValueNotifier<NexusCall?> current

The current call (null when idle). Listen to drive your call UI.

ivrCopy Anchor Link

final ValueNotifier<NexusIvrSession?> ivr

The current in-app IVR menu session (null when not in a menu). Drives the built-in NexusIvrOverlay; listen to build your own support-menu UI.

onIvrCopy Anchor Link

void Function(Map<String, dynamic> instruction)? onIvr

Optional hook for IVR prompts returned by DTMF (play/collect instructions).

init()Copy Anchor Link

Future<void> init()

Turnkey setup — called automatically when voiceEnabled. Wires the SDK's BUILT-IN WebRTC engine + native call UI (CallKit/ConnectionService) and registers this device for incoming-call push so calls ring even when the app is killed. Developers do NOT call this.

rebindIdentity()Copy Anchor Link

Future<void> rebindIdentity()

Re-bind voice to the CURRENT identity — MUST be called after identify()/reset(). Voice initialises at app start (before login), so it first binds to voice:<deviceKey>; without re-binding, an identified user keeps listening on the device room and never rings on voice:<distinctId>. Re-joins the correct room and re-registers the push device under the new id.

useEngine()Copy Anchor Link

void useEngine(NexusVoiceEngine engine)

Advanced override — replace the built-in WebRTC engine.

Parameters

useCallKit()Copy Anchor Link

void useCallKit(NexusCallKit callKit)

Advanced override — replace the built-in native call UI.

Parameters

registerPushToken()Copy Anchor Link

Future<bool> registerPushToken({String? voipToken, String? fcmToken})

Register this device's push tokens (iOS VoIP / Android FCM) for incoming calls when the app is backgrounded/killed. The SDK does this automatically; call it yourself with a token if your app owns FCM/OneSignal and wants to hand the SDK the exact token. Returns true once a token was registered.

Parameters

Returns Future<bool>

ensurePermissions()Copy Anchor Link

Future<bool> ensurePermissions()

Request the microphone permission a voice call needs, returning whether it is granted. Call this from your onboarding (a foreground moment with UI context) so an incoming call answered later from a killed/background state — where no permission dialog can be shown — already has audio access. The SDK also pre-warms it on voice init, but calling it during onboarding with your own rationale is the best UX.

Returns Future<bool>

openMicrophoneSettings()Copy Anchor Link

Future<bool> openMicrophoneSettings()

Open this app's OS settings page so the user can grant the microphone after a permanent denial — iOS never re-prompts once the user has refused, so this is the only way back. Returns true if the settings page was opened.

Returns Future<bool>

placeCall()Copy Anchor Link

Future<NexusCall?> placeCall({required String to, VoiceEndpointType type = VoiceEndpointType.app, String? callerId, String? displayName, String? callerDisplayName, String? callerAvatarUrl, bool record = false, Map<String, dynamic> metadata = const {}})

Place a call to to — a Nexus identity (app), a phone number (pstn) or a SIP URI. This device joins as a WebRTC leg; the control plane dials to.

Parameters

Returns Future<NexusCall?>

handleIncomingPush()Copy Anchor Link

Future<void> handleIncomingPush(Map<String, dynamic> data, {bool alreadyRinging = false})

Handle an incoming-call push/data message. Call this from your FCM / VoIP push handler with the payload the backend sent ({sessionId, from, ...}). Shows the native incoming UI and arms answer/decline.

Parameters

answer()Copy Anchor Link

Future<void> answer([String? sessionId])

Answer the current inbound call — join as a WebRTC leg.

Parameters

decline()Copy Anchor Link

Future<void> decline()

Decline the current inbound call.

startIvr()Copy Anchor Link

Future<bool> startIvr(String flowId)

Open an in-app IVR menu (a visual phone-tree) for flowId — e.g. a support entry point built in the dashboard. The built-in NexusIvrOverlay renders it; the caller taps keys to navigate, and the SDK auto-connects a real call when the flow routes to an agent. Returns false if the menu couldn't start.

Parameters

Returns Future<bool>

pressIvrKey()Copy Anchor Link

Future<void> pressIvrKey(String digit)

Press a key in the current IVR menu.

Parameters

endIvr()Copy Anchor Link

void endIvr()

Dismiss the IVR menu (the user backed out).

hangup()Copy Anchor Link

Future<void> hangup()

setMuted()Copy Anchor Link

Future<void> setMuted(bool muted)

Parameters

setSpeakerphone()Copy Anchor Link

Future<void> setSpeakerphone(bool on)

Parameters

setHold()Copy Anchor Link

Future<void> setHold(bool held)

Parameters

sendDtmf()Copy Anchor Link

Future<void> sendDtmf(String digit)

Parameters

setPresence()Copy Anchor Link

Future<void> setPresence(String status)

Parameters

dispose()Copy Anchor Link

void dispose()

VoiceCallStateCopy Anchor Link

enum VoiceCallState

Call state — the subset a client observes (mirrors the server machine).

VoiceCallStateXCopy Anchor Link

extension VoiceCallStateX on VoiceCallState

isTerminalCopy Anchor Link

bool get isTerminal

isActiveCopy Anchor Link

bool get isActive

VoiceEndpointTypeCopy Anchor Link

enum VoiceEndpointType

VoiceCallDirectionCopy Anchor Link

enum VoiceCallDirection

NexusJoinTokenCopy Anchor Link

Everything a client needs to join the media plane for one leg. Minted by the control plane; the client never fabricates any of it.

NexusJoinTokenCopy Anchor Link

const NexusJoinToken({required this.room, required this.token, required this.url, this.turnUrls = const [], this.turnUsername, this.turnPassword})

Parameters

tryParse()Copy Anchor Link

static NexusJoinToken? tryParse(Map<String, dynamic>? join)

Parameters

Returns NexusJoinToken?

roomCopy Anchor Link

final String room

tokenCopy Anchor Link

final String token

urlCopy Anchor Link

final String url

turnUrlsCopy Anchor Link

final List<String> turnUrls

turnUsernameCopy Anchor Link

final String? turnUsername

turnPasswordCopy Anchor Link

final String? turnPassword

CallQualitySampleCopy Anchor Link

One transport-quality sample the engine emits; reported to the control plane and surfaced to the app for a live quality indicator.

CallQualitySampleCopy Anchor Link

const CallQualitySample({this.rttMs, this.jitterMs, this.packetLoss, this.bitrateKbps, this.mos, this.codec, this.candidateType})

Parameters

rttMsCopy Anchor Link

final int? rttMs

jitterMsCopy Anchor Link

final int? jitterMs

packetLossCopy Anchor Link

final double? packetLoss

bitrateKbpsCopy Anchor Link

final int? bitrateKbps

mosCopy Anchor Link

final double? mos

codecCopy Anchor Link

final String? codec

candidateTypeCopy Anchor Link

final String? candidateType

toJson()Copy Anchor Link

Map<String, Object?> toJson()

Returns Map<String, Object?>

NexusCallCopy Anchor Link

Immutable snapshot of the current call, exposed via a ValueListenable.

NexusCallCopy Anchor Link

const NexusCall({required this.sessionId, required this.direction, required this.state, this.legId, this.remoteAddress, this.remoteName, this.remoteAvatar, this.muted = false, this.onHold = false, this.speakerphone = false, this.startedAt, this.connectedAt, this.quality, this.endReason, this.metadata = const {}})

Parameters

sessionIdCopy Anchor Link

final String sessionId

legIdCopy Anchor Link

final String? legId

directionCopy Anchor Link

final VoiceCallDirection direction

stateCopy Anchor Link

final VoiceCallState state

remoteAddressCopy Anchor Link

final String? remoteAddress

remoteNameCopy Anchor Link

final String? remoteName

remoteAvatarCopy Anchor Link

final String? remoteAvatar

mutedCopy Anchor Link

final bool muted

onHoldCopy Anchor Link

final bool onHold

speakerphoneCopy Anchor Link

final bool speakerphone

startedAtCopy Anchor Link

final DateTime? startedAt

connectedAtCopy Anchor Link

final DateTime? connectedAt

qualityCopy Anchor Link

final CallQualitySample? quality

endReasonCopy Anchor Link

final String? endReason

metadataCopy Anchor Link

final Map<String, dynamic> metadata

copyWith()Copy Anchor Link

NexusCall copyWith({String? legId, VoiceCallState? state, bool? muted, bool? onHold, bool? speakerphone, DateTime? connectedAt, CallQualitySample? quality, String? endReason})

Parameters

Returns NexusCall

NexusVoiceEngineCopy Anchor Link

abstract class NexusVoiceEngine

The media-transport seam. Nexus Voice's control plane is engine-agnostic; the actual WebRTC connection to the media plane (LiveKit) is provided by a NexusVoiceEngine. Ship a real engine by registering one via Nexus.instance.voice.useEngine(...) — e.g. a thin adapter over livekit_client (see the SDK README). Keeping media out of the core keeps the base package dependency-light and lets any transport slot in.

statesCopy Anchor Link

Stream<VoiceEngineState> get states

Transport state changes (local connection to the media room).

remoteCountCopy Anchor Link

Stream<int> get remoteCount

Number of REMOTE participants in the room. The call is "connected" (the other party answered/joined) when this is > 0; it drops when they leave.

qualityCopy Anchor Link

Stream<CallQualitySample> get quality

Periodic quality samples (reported to the control plane + shown in-app).

connect()Copy Anchor Link

Future<void> connect(NexusJoinToken token)

Connect to the media plane for a leg and start capturing/playing audio.

Parameters

disconnect()Copy Anchor Link

Future<void> disconnect()

Tear down the media connection.

setMuted()Copy Anchor Link

Future<void> setMuted(bool muted)

Parameters

setSpeakerphone()Copy Anchor Link

Future<void> setSpeakerphone(bool on)

Parameters

sendDtmf()Copy Anchor Link

Future<void> sendDtmf(String digit)

Send a DTMF digit over the media session (RFC 4733).

Parameters

VoiceEngineStateCopy Anchor Link

enum VoiceEngineState

NoopVoiceEngineCopy Anchor Link

class NoopVoiceEngine implements NexusVoiceEngine

Default engine when none is registered: it does NO media. It logs and reports a connected state so control-plane flows can be exercised end-to-end without audio (useful in tests / before wiring a real transport). It never throws.

statesCopy Anchor Link

Stream<VoiceEngineState> get states

remoteCountCopy Anchor Link

Stream<int> get remoteCount

qualityCopy Anchor Link

Stream<CallQualitySample> get quality

connect()Copy Anchor Link

Future<void> connect(NexusJoinToken token)

Parameters

disconnect()Copy Anchor Link

Future<void> disconnect()

setMuted()Copy Anchor Link

Future<void> setMuted(bool muted)

Parameters

setSpeakerphone()Copy Anchor Link

Future<void> setSpeakerphone(bool on)

Parameters

sendDtmf()Copy Anchor Link

Future<void> sendDtmf(String digit)

Parameters

NexusCallKitCopy Anchor Link

abstract class NexusCallKit

Native calling seam — CallKit (iOS) / ConnectionService (Android) + VoIP push. The SDK reports call lifecycle to the OS so incoming calls ring on the lock screen and in-call actions come from the system UI. Provide a real implementation (e.g. over flutter_callkit_incoming) via Nexus.instance.voice.useCallKit(...). The default is a no-op so the SDK runs without the native dependency.

actionsCopy Anchor Link

Stream<CallKitAction> get actions

Actions the user takes from the system UI (answer / decline / mute / …).

reportIncoming()Copy Anchor Link

Future<void> reportIncoming({required String callId, required String handle, String? displayName, String? avatarUrl, bool hasVideo = false})

Show the system incoming-call UI. Returns when displayed.

Parameters

reportOutgoing()Copy Anchor Link

Future<void> reportOutgoing({required String callId, required String handle, String? displayName})

Start a native OUTGOING call entry (configures the VoIP audio session).

Parameters

reportConnected()Copy Anchor Link

Future<void> reportConnected(String callId)

Tell the OS the call connected (starts its timer / active-call UI).

Parameters

reportEnded()Copy Anchor Link

Future<void> reportEnded(String callId)

Tell the OS the call ended (dismisses the call UI).

Parameters

voipToken()Copy Anchor Link

Future<String?> voipToken()

The current VoIP push token (APNs PushKit / FCM), for the app to register with the backend so incoming calls can wake a killed app. Null if none.

Returns Future<String?>

CallKitActionTypeCopy Anchor Link

enum CallKitActionType

CallKitActionCopy Anchor Link

CallKitActionCopy Anchor Link

const CallKitAction(this.type, this.callId, {this.value})

Parameters

typeCopy Anchor Link

final CallKitActionType type

callIdCopy Anchor Link

final String callId

valueCopy Anchor Link

final Object? value

NoopCallKitCopy Anchor Link

class NoopCallKit implements NexusCallKit

No-op default. The SDK still works for in-app (foreground) calling; the OS call UI simply isn't shown until a real CallKit implementation is registered.

actionsCopy Anchor Link

Stream<CallKitAction> get actions

reportIncoming()Copy Anchor Link

Future<void> reportIncoming({required String callId, required String handle, String? displayName, String? avatarUrl, bool hasVideo = false})

Parameters

reportOutgoing()Copy Anchor Link

Future<void> reportOutgoing({required String callId, required String handle, String? displayName})

Parameters

reportConnected()Copy Anchor Link

Future<void> reportConnected(String callId)

Parameters

reportEnded()Copy Anchor Link

Future<void> reportEnded(String callId)

Parameters

voipToken()Copy Anchor Link

Future<String?> voipToken()

Returns Future<String?>

NexusVoiceOverlayCopy Anchor Link

class NexusVoiceOverlay extends StatefulWidget

The SDK's built-in, auto-shown call screen. Renders full-screen whenever there is an active call (Nexus.instance.voice.current) — outbound and incoming — with mute / speaker / hold / hangup (and accept / decline while ringing inbound). Auto-mounted when voiceEnabled; opt out with NexusConfig(autoShowOverlay: false) and place your own UI, or wrap NexusVoiceOverlay yourself.

NexusVoiceOverlayCopy Anchor Link

const NexusVoiceOverlay({super.key, this.child})

Parameters

childCopy Anchor Link

final Widget? child

NexusIvrStatusCopy Anchor Link

enum NexusIvrStatus

State of an in-app IVR (visual phone-tree) session. The caller sees the current prompt; when awaitingInput is true a keypad is shown and each press calls NexusVoice.pressIvrKey. On reaching a "talk to an agent" step the SDK connects a real call automatically (status → connecting), and the NexusIvrSession clears once that call takes over.

NexusIvrSessionCopy Anchor Link

NexusIvrSessionCopy Anchor Link

const NexusIvrSession({required this.sessionId, this.prompt, this.awaitingInput = false, this.maxDigits = 1, this.status = NexusIvrStatus.active, this.endedReason})

Parameters

sessionIdCopy Anchor Link

final String sessionId

promptCopy Anchor Link

final String? prompt

awaitingInputCopy Anchor Link

final bool awaitingInput

maxDigitsCopy Anchor Link

final int maxDigits

statusCopy Anchor Link

final NexusIvrStatus status

endedReasonCopy Anchor Link

final String? endedReason

copyWith()Copy Anchor Link

NexusIvrSession copyWith({String? prompt, bool? awaitingInput, int? maxDigits, NexusIvrStatus? status, String? endedReason})

Parameters

Returns NexusIvrSession

NexusIvrOverlayCopy Anchor Link

class NexusIvrOverlay extends StatelessWidget

The SDK's built-in IVR menu screen. Auto-shown whenever an IVR session is active (alongside NexusVoiceOverlay); opt out with autoShowOverlay: false and build your own from Nexus.instance.voice.ivr.

NexusIvrOverlayCopy Anchor Link

const NexusIvrOverlay({super.key})

Parameters

FunctionsCopy Anchor Link

showNexusIncomingCall()Copy Anchor Link

Future<void> showNexusIncomingCall(Map<dynamic, dynamic> data)

Show the native incoming-call UI directly from a voice push payload.

Only needed on Android, where the incoming-call push is an FCM data message the SDK handles in a background Dart isolate. On iOS the ring is raised natively from the APNs VoIP (PushKit) payload before Dart is involved at all, so nothing here runs on that path.

The SDK wires its own FCM background handler, so apps do not normally call this; it stays public for apps that own their FCM handler end to end.

Parameters