NexusVoice class

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.

Constructors

NexusVoice(NexusHttp _http, NexusIdentity _identity, NexusRealtime _realtime)

Properties

current → ValueNotifier<NexusCall?>

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

final

hashCode → int

The hash code for this object.

no setter, inherited

ivr → ValueNotifier<NexusIvrSession?>

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.

final

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

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

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

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

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

decline() → Future<void>

Decline the current inbound call.

dispose() → void

endIvr() → void

Dismiss the IVR menu (the user backed out).

ensurePermissions() → Future<bool>

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.

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

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.

hangup() → Future<void>

init() → Future<void>

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.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

openMicrophoneSettings() → Future<bool>

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.

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

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.

pressIvrKey(String digit) → Future<void>

Press a key in the current IVR menu.

rebindIdentity() → Future<void>

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.

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

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.

sendDtmf(String digit) → Future<void>

setHold(bool held) → Future<void>

setMuted(bool muted) → Future<void>

setPresence(String status) → Future<void>

setSpeakerphone(bool on) → Future<void>

startIvr(String flowId) → Future<bool>

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.

toString() → String

A string representation of this object.

inherited

useCallKit(NexusCallKit callKit) → void

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

useEngine(NexusVoiceEngine engine) → void

Advanced override — replace the built-in WebRTC engine.

Operators

operator ==(Object other) → bool

The equality operator.

inherited