Configuration Guide

​

Overview

• Features: Toggle UI components and functionality
• Appearance: Customize visual styling and branding
• Locale: Set interface and dictation languages, plus custom string overrides

​

Feature Toggles

​

interactionTitle

• You want a more minimal, streamlined interface
• You’re managing the interaction title externally in your application
• The title is redundant with information already displayed in your host application

• Users need to see or edit the interaction title within the Assistant
• The title provides important context for the current session
• You want users to be able to identify different interactions

​

aiChat

• You want to restrict AI chat functionality for compliance or policy reasons
• Your workflow doesn’t require AI assistance features
• You’re providing alternative support channels for user questions

• Users benefit from AI-powered assistance during documentation
• You want to provide contextual help and clarifications
• AI chat enhances the user experience and productivity

​

documentFeedback

• You handle document feedback through external systems
• Feedback collection is not part of your workflow
• You want to simplify the interface by removing feedback mechanisms

• You want to collect user feedback to improve document quality
• Feedback helps identify issues or areas for improvement
• You want users to have a way to report problems with generated documents

​

navigation

• You want users to have full access to Assistant features
• Users need to browse and manage templates
• Users should be able to access settings and preferences
• Archive functionality is needed for your workflow

• You want a focused, minimal interface for specific workflows
• Navigation is handled externally in your application
• You’re creating a single-purpose integration that doesn’t need full navigation

• /templates - Browse and create document templates
• /settings/preferences - Edit defaults like languages and default session settings
• /settings/input - Edit dictation input settings
• /settings/account - Edit general account settings
• /settings/archive - View items in and restore from archive

​

virtualMode

• Consultations are conducted in-person
• Recording happens locally or through local audio devices
• You’re integrating with physical clinic environments
• The consultation type is explicitly in-person

• Consultations are conducted remotely (telemedicine)
• Audio is captured through web-based or remote systems
• The default virtual consultation workflow applies
• Remote consultation is the primary or only mode

• Virtual mode (true): Optimized for remote consultations with web-based audio capture
• Live mode (false): Optimized for in-person consultations with local audio handling

​

syncDocumentAction

• You want users to be able to sync documents directly from the Assistant interface
• Direct EHR synchronization is part of your workflow
• Users need immediate access to sync functionality

• Document syncing is handled externally through your application
• You manage document export through your own systems
• You want to control the sync process outside the Assistant

​

Appearance Customization

​

Primary Color

• You want to maintain brand consistency with your host application
• Your application has a specific brand color palette
• You need to match existing design systems or style guides
• Visual consistency across your integrated experience is important

• Brand consistency is not a priority
• You prefer Corti’s default accessible color scheme
• You want to minimize customization complexity

• Button backgrounds and hover states
• Link colors
• Focus indicators and active states
• Accent elements and highlights
• Selected states and active UI elements

• The color must meet WCAG 2.2 AA contrast requirements (see WCAG Compliance)
• The color is applied across all UI states (default, hover, active, focus, disabled)
• Test thoroughly to ensure accessibility and usability

await api.configure({
  appearance: {
    primaryColor: "#00a6ff"
  }
});

​

WCAG 2.2 AA Compliance

​

Required WCAG 2.2 AA Criteria

• 1.4.3 Contrast (Minimum):
  • Normal text: ≥ 4.5:1 contrast ratio
  • Large text: ≥ 3:1 contrast ratio
• 1.4.11 Non-text Contrast:
  • UI boundaries, focus rings, and selected states: ≥ 3:1 contrast ratio
• 2.4.11 Focus Not Obscured (Minimum):
  • Focus indicators must remain visible and unobstructed

​

Best Practices for Color Customization

1. Test contrast ratios: Use tools like WebAIM Contrast Checker to verify your color choices
2. Test all states: Verify contrast for default, hover, active, disabled, and focus states
3. Test on all backgrounds: Ensure your color works on both light and dark backgrounds if applicable
4. Maintain focus visibility: Ensure focus indicators remain clearly visible with your custom color
5. Consider color blindness: Test with color blindness simulators to ensure usability

​

Locale Settings

​

Interface Language

• Your application serves users in specific languages
• You want to ensure a consistent language experience
• Users prefer a specific interface language regardless of browser settings
• You’re building a localized application

• You want to respect user browser/OS language preferences
• Language detection should be automatic
• You support multiple languages and want automatic selection

​

Dictation Language

• Users dictate in a language different from the interface language
• You need to support multilingual dictation
• Regional variations require specific language codes (e.g., "en-GB" vs "en")

• Region-specific: Different regions (EU, US) support different dictation languages
• Separate from interface language: Interface and dictation languages are independent
• Must be valid: The language code must be supported in your region (see Available Dictation Languages)

​

String Overrides

{
  "string.key": "Custom text",
  "another.key": "Another custom text"
}

• You need to customize button labels to match your terminology
• You want to localize specific strings that aren’t covered by interface language
• You need to match your application’s terminology (e.g., “EHR” vs “EMR”)
• You want to provide context-specific labels

• Only specific keys are available for override (see Available String Overrides)
• Not all UI strings can be customized
• Overrides apply regardless of interface language

​

Available String Overrides

​

Available Interface Languages

​

Available Dictation Languages

​

EU Region

​

US Region

​

Configuration Structure

{
  features: {
    interactionTitle: boolean,
    aiChat: boolean,
    documentFeedback: boolean,
    navigation: boolean,
    virtualMode: boolean,
    syncDocumentAction: boolean
  },
  appearance: {
    primaryColor: string | null
  },
  locale: {
    interfaceLanguage: string | null,
    dictationLanguage: string,
    overrides: Record<string, string>
  }
}

​

Best Practices

​

Configuration Timing and Lifecycle

• Adapting to different user roles or contexts
• Responding to user preferences changes
• Switching between different workflow modes

​

Incremental Configuration

• Update only features to change UI visibility
• Update only appearance to change branding
• Update only locale to change language settings

​

Reading Current Configuration

• Read the current state of all settings
• Verify that your configuration was applied correctly
• Build upon existing configuration rather than replacing it entirely

​

Error Handling

• Handle configuration failures: Configuration may fail due to invalid values, network issues, or other errors
• Provide fallbacks: Have default configuration ready in case of failures
• Log errors appropriately: Log configuration errors for debugging while maintaining user experience
• Validate before applying: Validate configuration values (especially colors and language codes) before sending them

​

Accessibility Best Practices

• Always test color contrast ratios using tools like WebAIM Contrast Checker
• Test all UI states: default, hover, active, disabled, and focus
• Ensure focus indicators remain clearly visible
• Test on both light and dark backgrounds if applicable
• Consider color blindness: Test with simulators to ensure usability

• Ensure that disabling features doesn’t break keyboard navigation
• Verify that screen readers can still navigate the interface
• Test that essential functionality remains accessible when features are disabled
• Consider the impact on users who rely on specific features

• Ensure interface language changes don’t break layout or functionality
• Test that all UI elements are properly localized
• Verify that right-to-left languages (if supported) work correctly

​

Performance Optimization

​

User Experience Guidelines

• What features do users actually need for their tasks?
• What can be simplified or hidden to reduce cognitive load?
• How does the Assistant fit into the broader application workflow?

• Use interface language settings that match your application’s user preferences
• Set dictation language based on the actual language users will speak
• Consider allowing users to change settings if navigation is enabled

• Configure differently for different user roles (e.g., physicians vs. nurses)
• Adapt configuration based on consultation type (virtual vs. in-person)
• Consider workflow-specific configurations for different use cases

​

Security and Compliance

• Ensure customizations maintain compliance with relevant regulations (HIPAA, GDPR, etc.)
• Document any customizations that affect compliance
• Test that disabled features don’t impact required functionality

​

Testing Recommendations

• Test with various color values
• Verify accessibility in all states
• Test with different screen sizes and resolutions

• Verify all supported languages work correctly
• Test interface language and dictation language combinations
• Ensure string overrides work as expected

​

Related Documentation

• API Reference - Complete reference for the configure action
• PostMessage API - Learn how to use the PostMessage integration method
• Window API - Learn how to use the Window API integration method
• Embedded API Overview - General overview of the embedded API