Provide Additional Clinical Context

Attach clinical context, medication orders, and encounter details to an ambient session with setSessionContext(with:) in the iOS SDK

Updated:

Starting with Mobile SDK v2.6.0+ on iOS SDK, you can attach structured medication orders to an ambient session’s context by passing SukiAmbientConstant.kOrdersInfo into setSessionContext(with:) after you create the session.

Learn more in the Medication orders section.

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.

All context parameters mentioned below are optional. Use one or more of these parameters to help Suki generate more accurate and relevant clinical notes. The absence of any parameter will not break existing functionality.

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.

How to decide what to send

All context parameters are optional, so the session still works if you send none of them. Send the parameters that match data you already have in your app or EHR, including partial context when that is all you can provide, and leave out any parameter you cannot fill yet.

When to call setSessionContext

1. Create the ambient session and wait for success.
2. Call setSessionContext(with:) with whatever context you have.
3. Start recording.
4. Call setSessionContext(with:) again later if more context becomes available. Each call updates or adds to the existing context.

If context is not ready when the session starts, you can still record and send context when it becomes available.

Match what you have to a context type

Use this table to pick which guide to open. If your app already has the data in the left column, pass that context type in setSessionContext(with:) and follow the linked guide for keys and examples.

Data you already have	Context type to pass
Patient demographics, patient id, or structured name	Patient info
Provider specialty or role in the encounter	Provider context
Visit type, care setting, reason for visit, or chief complaint	Visit context
An EMR identifier for this session	EMR info
LOINC codes for the note sections you want	Note sections
Known diagnoses or diagnosis codes for the visit	Diagnosis info
Medications prescribed during the ambient visit, and Medication orders is enabled	Orders info

You can send one parameter or several in the same setSessionContext(with:) call, and mix only the keys you need.

Things to keep in mind:

• Do not block session creation or recording because context is incomplete.
• Map fields from your EHR or scheduling system into the matching keys when those values exist.
• Omit keys you cannot populate, and do not invent placeholder values for required nested fields unless the field docs say they are optional.
• For orders info, Medication orders is not enabled by default, so contact Suki support if you need access. Incomplete order metadata can fail validation.

Set session context (optional but recommended)

After the session is created, call setSessionContext(with:) and pass a dictionary of optional parameters. In one call you can mix patient info, provider context, visit context, EMR info, note sections, diagnosis info, and medication orders, or send just one of them. For each parameter, see the keys and types in Additional context parameters. If you do not have data for a parameter yet, leave it out of the dictionary; call setSessionContext(with:) again when you want to add or change values.

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.

Code example

Swift

do {
    let contextDetail: [String: AnyHashable] = [
        SukiAmbientConstant.kPatientInfo: [
            SukiAmbientConstant.kBirthdate: Date(), // Use yyyy-mm-dd format
            SukiAmbientConstant.kGender: "FEMALE",
            SukiAmbientConstant.kPatientId: "emr-patient-42",
            SukiAmbientConstant.kPatientName: [
                SukiAmbientConstant.kPatientFamily: "Doe",
                SukiAmbientConstant.kPatientGiven: ["Jane", "Marie"],
                SukiAmbientConstant.kPatientSuffix: ["Jr"],
                SukiAmbientConstant.kPatientNameUse: "official"
            ] as [String: AnyHashable]
        ],
        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.kEmrInfo: [ // New in v2.6.0: Optional EMR info (string)
            SukiAmbientConstant.kTargetEmr: "<emr_identifier>" // Required: which EMR this session uses (string)
        ],
        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"
                    ]
                ]
            ]
        ],
        // New in v2.6.0: medication orders context parameter for suggesting medication orders
        SukiAmbientConstant.kOrdersInfo: [
            MedicationOrderKeys.kMedicationOrders: [
                [
                    MedicationOrderKeys.kDrugName: "Atorvastatin",
                    MedicationOrderKeys.kMedicationCode: [
                        SukiAmbientConstant.kCodeType: "<code_type>", // optional; coded values must match a supported catalog in your SDK version
                        SukiAmbientConstant.kCode: "<code>" // optional
                    ],
                    MedicationOrderKeys.kStrength: "10 mg", // optional
                    MedicationOrderKeys.kFormat: "tablet", // optional
                    MedicationOrderKeys.kRoute: "oral", // optional
                    MedicationOrderKeys.kLinkedDiagnosisCodes: [
                        [
                            SukiAmbientConstant.kCodeType: "ICD-10",
                            SukiAmbientConstant.kCode: "E78.5"
                        ]
                    ],
                    MedicationOrderKeys.kMetadata: [
                        MedicationOrderKeys.kOrigin: "EMR",
                        MedicationOrderKeys.kEncounterRelation: "CURRENT_ENCOUNTER"
                    ]
                    // Optional: MedicationOrderKeys.kDosage, kFrequency, kMedicationTiming, kStatus, kQuantityDispensed, kNumberOfRefills, kStartDate, kEndDate, kDurationInDays, kInstructions, etc

                ]
            ]
        ]
    ]

    try SukiAmbientCoreManager.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)
}

Call setSessionContext(with:) only after a session has been successfully created. Call createSession first and wait for it to succeed before calling setSessionContext.

Retrieve the generated note and structured data

• After you call setSessionContext with your additional clinical context (such as provider, patient, or visit details), you can use the Suki Mobile SDK to retrieve your results.

• Use the content(for:) method to retrieve the generated clinical note and extracted blocks. To pull structured output once processing completes, call getStructuredData(for:). The structured output includes all data the service produces from your specific context, including diagnoses and medication order payloads.

• For more information on how to retrieve these elements, read our guide on Check status and retrieve content.

All context parameters

Choose a context type for keys, types, and examples. Pass any combination of these parameters in setSessionContext(with:).

Patient Info

Demographics, partner or EMR patient id, and structured patient name for personalized note generation.

Provider Context

Specialty and provider role so notes match your specialty conventions and encounter role.

Visit Context

Visit type, encounter setting, reason for visit, and chief complaint for the encounter.

EMR Info

Target EMR identifier for the ambient session so Suki routes context to the right system.

Note Sections

LOINC section codes that define which clinical note sections you want in the generated note.

Diagnosis Info

Structured diagnosis notes and codes that help identify conditions discussed in the encounter.

Orders Info

Medication orders context, including drug details, linked diagnoses, and order metadata.

Best practices

Follow these practices to ensure reliable session management:

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

• Store the session ID: Save the sessionId returned from createSession immediately. Use it for recording controls and session-scoped APIs.

• 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.

• Medication orders: If you send MedicationOrderKeys.kMedicationOrders under kOrdersInfo, include required fields per order and valid metadata values, or the SDK can reject the update.

• 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 a 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 partnerId 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. For medication orders, confirm required fields per order, valid metadata values, and at least one linked diagnosis code object.
• 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

Recording controls - Guide to learn how to start recording and manage the recording lifecycle.