Initialize Dragon Copilot SDK for JavaScript

To initialize the Dragon Copilot SDK, call DragonCopilotSDK.dragon.initialize with initialization options.

Prerequisites

• You've added the Dragon Copilot SDK to your page.

• You've registered event handlers for events that are raised when you initialize the SDK. For example, the list of connected microphones.

Initialization options

For detailed information on the data types used by the initialization options, see the API reference.

Property	Description
services	Type: String Required: Yes Region code for the Dragon Copilot service the user is connecting to. This can be one of: us - USA ca - Canada de - Germany fr - France uk - United Kingdom
applicationName	Type: String Required: Yes The name of the application integrating the SDK.
authentication	Type: AuthenticationOptions Required: Yes Your app authenticates with Dragon Copilot using a callback provided here.
partnerGuid	Type: String Required: Yes You receive a partner GUID when you onboard as a Dragon Copilot SDK partner.
enableAll	Type: Boolean Required: No Default: True Enables speech recognition for all text fields.
speechOptions	Type: SpeechOptions Required: No The language and topic (i.e. specialty) for speech recognition in dictation mode.
containerSelector	Type: String Required: No The CSS selector of the DOM element which serves as a direct or indirect container for the text controls to be speech-enabled. This DOM element will be monitored by the SDK for DOM changes. If not provided, the SDK defaults to using the document body as the container.
correctionOptions	Type: CorrectionOptions Required: No Correction-related configuration options. To enable correction menu APIs and events, set InitializationOptions.correctionOptions.enableCorrectionMenu to true.
useConsoleLogger	Type: Boolean or ConsoleLoggerOptions Required: No Default: False Enables console logging or provides logger options.
environmentId	Type: String Required: No The user's environment ID from Dragon admin center.
customControlOptions	Type: CustomControlOptions Required: No Provides the set of custom controls.
dispatchAllCommands	Type: Boolean Required: No Default: False If true, dispatches all recognized commands.
traceId	Type: String Required: No Trace ID for logging and diagnostics.
isAmbientEnabled	Type: Boolean Required: No Default: False Enables/disables ambient recording mode.
isDictationEnabled	Type: Boolean Required: No Default: True Enables/disables dictation mode.
platformGuid	Type: String Required: No The platform GUID for integration.
daxProductId	Type: String Required: No The DAX product ID.
preferredMicrophone	Type: PreferredMicrophone Required: No Sets the preferred microphone.
buttonPreferences	Type: Partial<MicrophoneButtonPreferences> Required: No Microphone button settings.
navigationOptions	Type: Partial<NavigationOptions> Required: No Field delimiter and navigation preferences for Dragon Copilot texts.
clientType	Type: ClientType Required: No Type of client, for mobile mic implementations.
additionalSystemCommandSpokenForms	Type: AdditionalSystemCommandSpokenForms Required: No Extends built-in system commands with custom spoken forms while preserving their original built-in spoken form.
mobileMicOptions	Type: MobileMicOptions Required: No Enables/disables mobile mic functionality.
autotextOptions	Type: AutotextOptions Required: No Default: True Enables/disables Dragon Copilot text functionality.
isCommandWithoutPauseEnabled	Type: Boolean Required: No Enables the user to say a voice command immediately after dictation without a pause.
disabledSystemCommands	Type: Set<DisableableSystemCommand> Required: No Disables the specified Dragon Copilot standard voice commands. For a list of commands you can disable, see Disable Dragon Copilot standard commands and the API reference. Use this option to override the default Dragon Copilot behavior for these voice commands with your own application commands.

Examples

Minimal initialization

await DragonCopilotSDK.dragon.initialize({
  services: "us",
  authentication: {
    acquireAccessToken: acquireAccessTokenCallback,
  },
  partnerGuid: "MyPartnerGuid",
  applicationName: "MyApp",
});

Advanced initialization

await DragonCopilotSDK.dragon.initialize({
  applicationName: "Sample2",
  enableAll: true,
  partnerGuid: settings.partnerGuid,
  authentication: {
    acquireAccessToken: acquireAccessTokenCallback,
  },
  services: "us",
  speechOptions: {
    language: "en-US",
    topic: dragon.Topics.GeneralMedicine,
  },
  useConsoleLogger: false,
  isAmbientEnabled: false,
  isDictationEnabled: true,
  daxProductId: "",
  traceId: "",
  customControlOptions: {
    webCustomControlTypes: {
      lexicalControl,
    },
  },
  dispatchAllCommands: true,
  environmentId: "test-app",
  platformGuid: "",
  preferredMicrophone: {
    label: "",
  },
  disabledSystemCommands: new Set([
    SystemCommands.ScratchThat,
    SystemCommands.CompoundThat,
    SystemCommands.Undo,
    SystemCommands.Redo,
    SystemCommands.BeginningOfField,
    SystemCommands.EndOfField,
  ]),
});

Initialization errors

The Dragon Copilot SDK can throw one of the following errors when you call DragonCopilotSDK.dragon.initialize():

Error type	Error message	Description
IntegrationError	services are required.	The ServiceConfig object isn't provided.
IntegrationError	dragonMedicalServer is required.	dragonMedicalServer is missing from the ServiceConfig object.
IntegrationError	dragonMedicalServer.url is required and must be a string.	The url under dragonMedicalServer is empty or missing.
IntegrationError	dragonMedicalServer.url must use HTTPS protocol	The url under dragonMedicalServer doesn't use HTTPS protocol.
IntegrationError	Invalid service URL	The url under dragonMedicalServer has an invalid domain.
Error(HTTP Error)	Failed to fetch service config	Applies to the CDN-hosted SDK: There was an HTTP error downloading the ServiceConfig details from https://download.microsoft.com/download/f6aaaef1-c23a-4d24-88e9-3b66d39e19de/dragon-copilot-sdk/serviceconfig/<region>.json.
Error(HTTP Error)	Failed to get dax endpoint. Status: <HTTPStatus>	The configService URL is provided with the ServiceConfig object but the SDK fails to get the DAX endpoint and Dragon Medical Server URL from the configuration service.
InternalError	Cookies disabled: Speech recognition is unavailable; make sure you have enabled cookies for your browser.	Cookies are disabled.
InternalError	Some features might not work because your browser version isn't supported. Please upgrade to the latest version.	The browser version isn't supported.

See also

API reference