NowVoiceService class - iOS

The NowVoiceService class manages voice agent sessions for a single ServiceNow instance.

Note:

Initialize a NowVoiceService by calling NowVoice - makeVoiceService(instanceUrl: URL) async throws.

Table 1. Properties

Name	Type	Description
configuration	NowServiceConfiguration	The service configuration for the ServiceNow instance.
voiceEnabled	Boolean	Flag that indicates whether voice is enabled on the instance. Valid values: true: Voice is enabled. false: Voice is turned off. Always true after a NowVoiceService is successfully initialized with makeVoiceService(instanceUrl:).
configurations	Array of NowVoiceEndpoints	List of available voice endpoint configurations retrieved from the instance.

NowVoiceService - startVoice(endpoint: NowVoiceEndpoint, uiConfiguration: NowVoiceUIConfiguration, callbacks: NowVoiceCallbacks, theme: NowVoiceThemeable) async

Creates a UIViewController containing the voice agent UI, ready to be presented in a modal.

The UIViewController manages the full voice session lifecycle, including teardown on dismissal.

This function fetches an OAuth access token automatically before launching the voice UI.

Table 2. Parameters

Name	Type	Description
endpoint	NowVoiceEndpoint	The voice agent channel to connect to. Obtain from NowVoiceService.configurations. Endpoints are retrieved from your ServiceNow instance's Mobile SDK settings.
uiConfiguration	NowVoiceUIConfiguration	Optional. Presentation options for the voice agent UI. If omitted, uses the default values for NowVoiceUIConfiguration.
callbacks	NowVoiceCallbacks	Optional. Callbacks for voice session events. If omitted, events are silently ignored.
theme	NowVoiceThemeable	Optional. The visual theme applied to the voice UI. Default: NowVoiceDefaultTheme

Table 3. Returns

Type	Description
UIViewController	A UIViewController containing the full-screen voice agent interface. Present it in a modal. Set modalPresentationStyle = .fullScreen for the intended experience.

The following code example shows how to call this function.

import NowVoice

let instanceUrl = URL(string: "https://your-instance.service-now.com")!

// Initialize a NowVoiceService
do {
    let voiceService = try await NowVoice.makeVoiceService(instanceUrl: instanceUrl)
} catch {
    // Handle NowServiceError
    print("Failed to create voice service: \(error)")
}

// Get the voice endpoint from instance SDK settings
guard let endpoint = voiceService.configurations.first else {
    // No voice endpoints configured on this instance.
    return
}

// Launch the voice agent UI
let vc = try await voiceService.startVoice(
    endpoint: endpoint,
    uiConfiguration: NowVoiceUIConfiguration(
        hidesPostCallTranscript: false,
        shouldBlockTranscriptSharing: false
    ),
    callbacks: NowVoiceCallbacks(
        onMuteStateChanged: { isMuted in
            // Update your UI to reflect the current mute state.
            print("Microphone muted: \(isMuted)")
        },
        onMessageReceived: { message in
            // Receive real-time transcript messages during the session.
            print("[\(message.role)]: \(message.text)")
        },
        onCallEnded: { conversationId, error in
            // Called when the voice session ends.
            if let error {
                print("Session ended with error: \(error)")
            } else {
                print("Session complete. Conversation ID: \(conversationId ?? "unknown")")
            }
        }
    ),
    theme: NowVoiceDefaultTheme()
)

//Present the voice agent UI in a full-screen modal
vc.modalPresentationStyle = .fullScreen
present(vc, animated: true)

NowVoiceService - updateTheme(theme: NowVoiceThemeable)

Updates the visual theme of the currently active voice UI.

This function has no effect if no voice session is currently active. To apply a visual theme at voice session launch, provide a theme when calling startVoice(endpoint:uiConfiguration:callbacks:theme:).

Table 4. Parameters

Name	Type	Description
theme	NowVoiceThemeable	The theme to apply to the active voice UI.

Table 5. Returns

Type	Description
None

The following code example updates the visual theme of the currently active voice UI.

import NowVoice

let instanceUrl = URL(string: "https://your-instance.service-now.com")!

do {
    let voiceService = try await NowVoice.makeVoiceService(instanceUrl: instanceUrl)
} catch {
    // Handle NowServiceError
    print("Failed to create voice service: \(error)")
}

struct MyVoiceTheme: NowVoiceThemeable {
    var color: NowUIColoring = MyAppColors()
}

// Update the theme while a voice session is active
voiceService.updateTheme(theme: MyVoiceTheme())