Create Session

Create a session and enrich it with detailed clinical context.

Overview

The Suki Mobile SDK provides methods to manage the entire lifecycle of an ambient session. This guide covers how to create a session and enrich it with detailed clinical context.

What Will You Learn?

In this guide, you will learn how to:

• Initialize an ambient session by calling the createSession(withSessionInfo:) method and storing the resulting sessionId.

• Provide crucial context for the note generation, including provider specialty, LOINC codes, and structured diagnosis information, using the recommended setSessionContext(with:) method.

• Understand and utilize session parameters, such as SukiAmbientConstant.kSessionId and SukiAmbientConstant.kMultilingual.

• Adhere to best practices for robust integration, including initializing the SDK before recording, handling SukiAmbientCoreError, and managing session IDs for future operations.

• Troubleshoot common issues, such as why session creation might fail or why the session context may not update.

Create An Ambient Session

Before you can start a recording, you must create a session.

Call the createSession(withSessionInfo:) method to initialize the session. Upon success, this method returns a sessionId that you must store to reference this session in future calls.

Swift

let sessionContext = [
            SukiAmbientConstant.kSessionId: <encounter-id>,
            SukiAmbientConstant.kIsMultilingual:isMultingual
        ] as [String : AnyHashable]        
        SukiAmbientCoreManager.shared.createSession(with: sessionContext, onCompletion: { result in
            switch result {
            case .success(let sessionResponse):
                print("Success")
            case .failure(let error):
                Print("error = \(error)")
            }
        })

Session Info Parameters

The withSessionInfo dictionary can contain the following keys:

SukiAmbientConstant.kSessionId · string

An optional unique identifier for the session. If not provided, the SDK generates one automatically.

SukiAmbientConstant.kMultilingual · boolean · default: "false"

Optional, enables multilingual processing for the session. The default value is false (English only). This setting applies to the entire session and cannot be changed mid-session.

Set Additional Context (Optional but Recommended)

After creating a session, you can add more detailed information by calling the setSessionContext(with:) method. This is the recommended way to provide context like provider specialty, LOINC codes, and structured diagnosis information.

This method uses an API that supports partial updates. You can call it multiple times to update or add different pieces of context after the session has been created.

Swift

do {
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kBirthdate: Date(), // Use yyyy-mm-dd format
            SukiAmbientConstant.kGender: "MALE"
        ],
        SukiAmbientConstant.kProviderContext: [
            SukiAmbientConstant.kSpeciality: "FAMILY_MEDICINE"
        ],
        SukiAmbientConstant.kSections: [
            [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
            [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
        ],
        SukiAmbientConstant.kDiagnosisInfo: [
            [
                SukiAmbientConstant.kDiagnosisNote: "Patient presents with chest pain",
                SukiAmbientConstant.kCodes: [
                    [
                        SukiAmbientConstant.kCodeType: "ICD-10",
                        SukiAmbientConstant.kCode: "R06.02",
                        SukiAmbientConstant.kCodeDescription: "Shortness of breath"
                    ]
                ]
            ]
        ]
    ]
    
    try SukiAmbientCore.shared.setSessionContext(with: contextDetail) { result in
        // Handle the asynchronous completion result.
    }
} catch {
    print(error)
}

You can only call setSessionContext(with:) after a session has been successfully created. You must provide valid speciality strings and codes.

Context Detail Parameters

The with dictionary can contain the following keys:

SukiAmbientConstant.kPatientInfo · dictionary

A dictionary for updating patient birthdate and gender.

SukiAmbientConstant.kProviderContext · dictionary

A dictionary containing the provider’s specialty.

SukiAmbientConstant.kSections · array of dictionaries

An array of dictionaries for mapping sections to specific LOINC codes.

You no longer need to provide section titles. The SDK will automatically generate the appropriate clinical sections based on the LOINC codes you provide.

SukiAmbientConstant.kDiagnosisInfo · array of dictionaries

An array of dictionaries for passing structured diagnosis context. Each dictionary can contain:

Show properties

kDiagnosisNote · string

An optional string with notes about the diagnosis.

kCodes · array of dictionaries

An array of one or more dictionaries for the diagnosis codes. Each code dictionary must contain:

Show properties

kCodeType · string · required

The type of code (e.g., “ICD-10”, “IMO”).

kCode · string · required

The diagnosis code.

kCodeDescription · string

An optional but recommended description of the code.

Best Practices And Error Handling

To ensure a robust integration, follow these best practices:

• Always ensure the SDK is initialized and a session is created before you call recording methods.

• Handle SukiAmbientCoreError in all operations to provide robust error feedback, especially for background and foreground transitions.

• Be aware of iOS limitations for background recording. A recording cannot be started while the app is in the background, and execution time is limited. Use local notifications to inform users if errors occur while the app is backgrounded.

• Store the unique recording or session ID for future operations, such as handling status changes or retrieving content.

FAQs

Why is the session creation failing?

The session creation can fail for several reasons:

Common causes:

• Invalid partner information
• Network connectivity issues
• Authentication token problems
• Missing microphone permissions

Debugging steps: Debug session creation failures by checking the completion handler result and catching session creation errors. Verify partner information, network connectivity, and required permissions.

Why is the session context not being updated?

The session context is not being updated because the setSessionContext method is not being called. You must ensure that you are calling the setSessionContext method after the session has been created.

Session created but user is not able to start recording?

The session is created but the user is not able to start recording because the session is not in a valid state. You must ensure that the session is in a valid state before the user can start recording. To start recording, you must call the start method.

Next Steps

After you create a session, proceed to our Recording Controls guide to learn how to manage the recording lifecycle.