Session Events & Delegates

Quick summary

The SDK uses a delegate pattern to broadcast important events during a session’s lifecycle. By conforming to the SukiAmbientSessionDelegate protocol and implementing sukiAmbient(sessionEvent:for:), you receive real-time updates about session state changes.

Use a switch statement to handle specific events like .started, .paused, .suggestionsGenerated, .sessionTerminatedByPeer, or .convertedToOfflineSession to update your UI or handle errors accordingly.

Last updated:July 2026

The SDK uses a delegate pattern to broadcast important events that occur during a session’s lifecycle. By conforming to the SukiAmbientSessionDelegate protocol, you can receive real-time updates and respond to state changes in your application, such as updating your UI or handling errors. What will you learn? In this guide, you will learn how to:

Use the SukiAmbientSessionDelegate protocol.
Implement the sukiAmbient(sessionEvent:for:) method.
Handle the events that are relevant to your application using a switch statement.

How to implement the session delegate

1. Conform to the protocol

First, declare that your class conforms to the SukiAmbientSessionDelegate protocol. You must also pass an instance of this delegate class when you initialize the SDK.

2. Implement the delegate method

Next, implement the sukiAmbient(sessionEvent:for:) method. The SDK calls this method every time a new session event occurs, providing the event type and the associated sessionId. Use a switch statement within this method to handle the events that are relevant to your application.

extension YourViewController: SukiAmbientSessionDelegate {
    func sukiAmbient(sessionEvent event: SukiAmbientCore.SessionEvent, for sessionId: SukiAmbientCore.SessionId) {
        // This method receives all session events for a given session ID.
        print("Received event: \(event) for session ID: \(sessionId)")

        // Use a switch statement to handle specific events.
        switch event {
        case .started:
            // Update your UI to show that recording has started.
            break
        case .suggestionsGenerated:
            // Notify the user that their note is ready.
            break
        case .convertedToOfflineSession:
            // Inform the user about the network issue.
            break
        case .sessionTerminatedByPeer(let reason): // New in v2.7.0
            // Another product cancelled or ended this live session.
            // Mic, stream, and local session are already cleared.
            // Update UI only. Do not call end(), cancel(), or clear().
            print("Peer terminated session: \(reason)")
            break
        // Handle other cases as needed for your app's logic.
        default:
            break
        }
    }
}

Available session events

The SessionEvent enum provides the following cases, which are grouped by category for clarity.

Recording lifecycle

enum

Recording lifecycle events for ambient sessions.

Hide cases

case

Triggered when the recording starts.

case

Triggered when the recording resumes after being paused.

case

Triggered when the recording is paused.

case

Triggered when the recording ends.

case

Triggered when the recording is cancelled.

case

Triggered when another Suki product cancels or ends the ambient session that is live in your app. Reason is .cancelled or .ended. Before this callback, the SDK stops the mic, deletes local audio, closes the stream, and clears the session state. Update the UI only. Do not call local end(), cancel(), or clear(), and do not call remote cancel or end for this direction.For more information, see Ambient interoperability.

Content generation

enum

Content generation events for note suggestions.

Hide cases

case

Triggered when suggestion generation begins.

case

Triggered when suggestions are successfully generated.

case

Triggered when suggestion generation fails.

Offline mode & uploading

enum

Offline mode and audio upload events.

Hide cases

case

Triggered when session is converted to offline mode.

case

Triggered when offline audio is pending upload.

case

Triggered when preparing offline audio for upload.

case

Triggered when audio upload is in progress.

case

Triggered when audio is successfully uploaded.

case

Triggered when audio upload fails.

case

Triggered when all audio upload retry attempts fail.

case

Triggered when uploaded audio is being processed.

case

Triggered when upload processing fails.

Audio interruptions

enum

Audio interruption events during recording.

Hide cases

case

Triggered when audio interruption begins (e.g., phone call).

case

Triggered when audio interruption ends.

All available session events cases

Below is the complete list of all available session events cases:

public enum SessionEvent {
    case started
    case resumed
    case paused
    case ended
    case cancelled
    case sessionTerminatedByPeer(reason:) // New in v2.7.0 (.cancelled | .ended | .unknown)
    case suggestionGenerationInProgress
    case suggestionsGenerated
    case suggestionsGenerationFailed
    case audioInterruptionStarted
    case audioInterruptionEnded
    case convertedToOfflineSession
    case pendingOfflineUpload
    case preparingOfflineUpload
    case uploadingAudio
    case audioUploadFailed
    case audioUploadAllRetryFailed
    case audioUploaded
    case processingUpload
    case processingUploadFailed
    case clearingBufferredAudio
    case clearedBufferredAudio
    case audioBufferFilled(withPercentage: Double) // New in v2.4.0
}

FAQs

Do I Have Any Other Events to Listen To?

Yes. Listen for sessionEvent callbacks. Each callback includes the sessionId for the ambient session that produced the event.

Can I Create a New Case Inside the `SessionEvent` Enum?

No, you cannot create a new case inside the SessionEvent enum. You must use the existing cases.

Why Do We Need So Many Cases for the `SessionEvent` Enum?

We have so many cases because we want to be able to handle all the possible events that can occur during a session.

Get Started

Concepts & Feature Guides

Resources

Session Events & Delegates

How to implement the session delegate

1. Conform to the protocol

2. Implement the delegate method

Available session events

Recording lifecycle

Content generation

Offline mode & uploading

Audio interruptions

All available session events cases

FAQs

​How to implement the session delegate

​1. Conform to the protocol

​2. Implement the delegate method

​Available session events

​Recording lifecycle

​Content generation

​Offline mode & uploading

​Audio interruptions

​All available session events cases

​FAQs

How to implement the session delegate

1. Conform to the protocol

2. Implement the delegate method

Available session events

Recording lifecycle

Content generation

Offline mode & uploading

Audio interruptions

All available session events cases

FAQs