Create Session

Learn how to create an ambient session and enrich it with detailed clinical context in the mobile SDK

Updated

The setSessionContext method in the mobile SDK now accepts new optional parameters like:

• visit_type
• encounter_type
• provider_role
• reason_for_visit
• chief_complaint

You can now provide these parameters to help improve note generation accuracy.

Quick Summary

The createSession(withSessionInfo:) method creates a new ambient session and returns a sessionId that you use for all subsequent operations. You can optionally provide session context like patient information, provider specialty, and note sections to improve note quality.

The method handles the session creation asynchronously and returns a result that you can use to track success or handle errors. Store the sessionId securely as you’ll need it for recording controls and content retrieval.

Last updated:December 2025

Overview

Before you can start recording audio and generating clinical notes, you must create an ambient session. This guide shows you how to create a session and provide clinical context that helps Suki generate more accurate notes.

What Will You Learn?

In this guide, you will learn how to:

• Create an ambient session using the createSession(withSessionInfo:) method
• Store the session ID returned from session creation for future operations
• Provide clinical context using the setSessionContext(with:) method to improve note quality
• Understand what information to provide and when to provide it

Create An Ambient Session

To start capturing audio and generating notes, you must first create a session. The session acts as a container that holds all the audio data and context for a single patient encounter.

Call the createSession(withSessionInfo:) method to create a new session. When successful, this method returns a sessionId that you must store to use for recording and retrieving content later.

Swift

let sessionContext = [
    SukiAmbientConstant.kSessionId: <encounter-id>,
    SukiAmbientConstant.kIsMultilingual: isMultilingual
] as [String : AnyHashable]

SukiAmbientCoreManager.shared.createSession(with: sessionContext, onCompletion: { result in
    switch result {
    case .success(let sessionResponse):
        // Store the sessionId from sessionResponse for future use
        let sessionId = sessionResponse.sessionId
        print("Session created successfully: \(sessionId)")
    case .failure(let error):
        print("Error creating session: \(error)")
    }
})

Session Info Parameters

The withSessionInfo dictionary accepts the following optional parameters:

SukiAmbientConstant.kSessionId · string

An optional unique identifier for the session. If you don’t provide this, the SDK automatically generates a session ID for you. Use this if you want to use your own encounter ID or session identifier.

SukiAmbientConstant.kMultilingual · boolean · default: "false"

Enables multilingual processing for the session. Set this to true if the conversation will be in languages other than English. The default value is false (English only). Once set, this cannot be changed for the session.

Important: Always store the sessionId returned from createSession. You’ll need it to:

• Start recording
• Check session status
• Retrieve generated content
• Update session context

Provide Clinical Context (Optional but Recommended)

After creating a session, you can provide additional clinical information using the setSessionContext(with:) method. This context helps Suki’s AI generate more accurate and relevant clinical notes.

Why provide context?

• Better note quality: More accurate sections and diagnoses
• Specialty-specific formatting: Notes match your medical specialty
• Structured organization: Notes organized by the sections you need
• Diagnosis accuracy: Better identification of conditions discussed

You can call setSessionContext(with:) multiple times. Each call updates or adds to the existing context. This allows you to provide information as it becomes available in your app.

Swift Expandable

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.kProviderRole: "Primary/Attending" // New in v2.5.0: Optional provider role (Primary/Attending or Consulting)
        ],
        SukiAmbientConstant.kVisitContext: [ 
          // New in v2.5.0: Visit context parameters for improved note generation
            SukiAmbientConstant.kVisitType: "Established patient", // Optional: New Patient / Intake, Established patient, Wellness, ED
            SukiAmbientConstant.kEncounterType: "ambulatory", // Optional: ambulatory, inpatient, ED
            SukiAmbientConstant.kReasonForVisit: "Annual checkup", // Optional: String, max 255 characters
            SukiAmbientConstant.kChiefComplaint: "Routine follow-up" // Optional: String, max 255 characters
        ],
        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
        switch result {
        case .success:
            print("Context updated successfully")
        case .failure(let error):
            print("Error updating context: \(error)")
        }
    }
} catch {
    print(error)
}

You can only call setSessionContext(with:) after a session has been successfully created. Make sure you call createSession first and wait for it to succeed before calling setSessionContext.

Context Parameters

All context parameters are optional. Provide only the information that is available in your application. The absence of any parameter will not break existing functionality.

SukiAmbientConstant.kPatientInfo · dictionary

Patient demographic information that helps personalize the note generation.

Hide properties

SukiAmbientConstant.kBirthdate · date

Patient’s date of birth in yyyy-mm-dd format.

SukiAmbientConstant.kGender · string

Patient’s gender. Valid values: “MALE” or “FEMALE”.

SukiAmbientConstant.kProviderContext · dictionary

Information about the healthcare provider to tailor note generation to your specialty and role.

Hide properties

SukiAmbientConstant.kSpeciality · string

The provider’s medical specialty (e.g., “FAMILY_MEDICINE”, “CARDIOLOGY”). This helps format notes according to your specialty’s conventions.

SukiAmbientConstant.kProviderRole · string

The provider’s role in the encounter. Valid values: “Primary/Attending” or “Consulting”. This helps distinguish between primary care providers and consulting specialists.

SukiAmbientConstant.kVisitContext · dictionary

Visit-related metadata that provides context about the type and purpose of the encounter.

Hide properties

SukiAmbientConstant.kVisitType · string

The type of patient visit. Valid values: “New Patient / Intake”, “Established patient”, “Wellness”, “ED”. This helps format notes appropriately for the visit type.

SukiAmbientConstant.kEncounterType · string

The setting where the encounter occurs. Valid values: “ambulatory”, “inpatient”, “ED”. This helps structure notes for the appropriate care setting.

SukiAmbientConstant.kReasonForVisit · string

A free-text description explaining why the patient is visiting. Maximum 255 characters. This helps focus the note on the primary reason for the visit.

SukiAmbientConstant.kChiefComplaint · string

The patient’s primary complaint or concern. Maximum 255 characters. This helps structure the note’s chief complaint section.

SukiAmbientConstant.kSections · array of dictionaries

An array of LOINC codes that specify which clinical note sections you want in the generated note. Each dictionary contains a LOINC code.

You only need to provide LOINC codes. The SDK automatically generates the appropriate clinical section titles based on the codes you provide.

Show example

SukiAmbientConstant.kSections: [
    [SukiAmbientConstant.kCode: "51848-0", SukiAmbientConstant.kCodeType: "loinc"],
    [SukiAmbientConstant.kCode: "11450-4", SukiAmbientConstant.kCodeType: "loinc"]
]

SukiAmbientConstant.kDiagnosisInfo · array of dictionaries

Structured diagnosis information that helps the AI identify and code conditions discussed during the encounter. Each dictionary represents one diagnosis.

Hide properties

SukiAmbientConstant.kDiagnosisNote · string

A text note describing the diagnosis or condition.

SukiAmbientConstant.kCodes · array of dictionaries

An array of diagnosis codes. Each code dictionary must contain:

Hide code properties

SukiAmbientConstant.kCodeType · string · required

The coding system used (e.g., “ICD-10”, “IMO”, “SNOMED”).

SukiAmbientConstant.kCode · string · required

The actual diagnosis code.

SukiAmbientConstant.kCodeDescription · string

A human-readable description of what the code represents. Recommended for clarity.

Best Practices

Follow these practices to ensure reliable session management:

• Always initialize the SDK first: Make sure SukiAmbientCore.shared.initialize() has been called successfully before creating a session.

• Store the session ID: Save the sessionId returned from createSession immediately. You’ll need it for all subsequent operations.

• Handle errors properly: Use the completion handler’s result to check for success or failure. Display appropriate error messages to users.

• Provide context when available: Call setSessionContext with any clinical information you have. Even partial context improves note quality.

• Call setSessionContext after createSession: Wait for createSession to succeed before calling setSessionContext.

• Handle background limitations: On iOS, you cannot start a recording while the app is in the background. Ensure your app is active before starting recording.

FAQs

Why is session creation failing?

Session creation can fail for several reasons:

Common causes:

• SDK not initialized: Make sure you’ve called initialize() before creating a session
• Invalid partner information: Check that your partner ID and provider information are correct
• Network connectivity issues: Ensure the device has an active internet connection
• Authentication token problems: Verify your token provider is returning valid tokens
• Missing microphone permissions: Ensure your app has microphone access permissions

How to debug: Check the error returned in the completion handler’s .failure case. The error will indicate the specific reason for failure.

Why isn't my session context updating?

The session context may not update if:

• Session not created: You must call createSession first and wait for it to succeed
• Method not called: Ensure you’re actually calling setSessionContext after session creation
• Invalid parameters: Check that specialty strings and codes match the expected formats
• Network error: The update request may have failed due to connectivity issues

How to verify: Check the completion handler result. If it returns .failure, examine the error to understand what went wrong.

Can I start recording immediately after creating a session?

Yes, once createSession succeeds and returns a sessionId, you can start recording. However, it’s recommended to call setSessionContext first if you have clinical context available, as this improves note quality.

The typical flow is:

1. Create session → Get sessionId
2. Set session context (optional but recommended)
3. Start recording

Next Steps

After you create a session and optionally set context, proceed to the Recording Controls guide to learn how to start recording and manage the recording lifecycle.