Define application commands

Voice commands are spoken words or phrases that initiate an action in an app. They enable users to control your app without physically interacting with the app UI.

The following types of voice commands are available:

• Standard commands: These are the Dragon Copilot built-in voice commands and include commands for dictation, navigation, correction, etc. They don't require or allow any handling by your app.

• Application commands: A voice command that you define in your speech-enabled app. Use application commands to enable voice activation of functionality specific to your app. For example:

  Control GUI elements: For example, the user says save report instead of selecting the Save button.

  Control workflows: For example, the user says show my last five reports for mister Brown instead of browsing through lists.

Use the APIs on this page to tell Dragon Copilot what to recognize as a voice command. Then implement event listeners for the resulting commandRecognized events and handle them in your app.

The spoken phrases for application commands must be unique. If they share a name with a standard command, the standard command is applied.

Command sets

Group together related commands into command sets. This is a prerequisite; the command set ID is a required property when you define your application commands.

You can enable and disable command sets. If you disable a command set, all commands in the set become inactive and the system no longer recognizes them until you enable the command set again. Use command sets to group related application commands so you can enable or disable them based on what the end user currently sees on the app UI or which app workflows are available to them.

Best practices

• Add or update application commands in batches.

  Adding or updating commands, command sets, and placeholders incurs performance costs. To minimize this impact and ensure best performance, add or update command sets, commands, and placeholders in batches rather than individually. Determine all required updates in advance and submit them in a single API call. Don't repeatedly invoke these APIs in a loop, as this approach degrades server performance and negatively affects the user experience.

  The examples below show the recommended approach.

• Define application commands before you initialize the SDK.

  We recommend you define all commands, command sets, and placeholders before you call the DragonCopilotSDK.dragon.initialize() function. This ensures that the system has the required context at startup, which improves initialization performance.

Add or update application commands

1. Add or update your command sets:

   const myCommandSet1 = {
     id: "cmdSet1",
     name: "My First CommandSet",
     description: "Description of my first command set",
   };
   
   const myCommandSet2 = {
     id: "cmdSet2",
     name: "My Second CommandSet",
     description: "Description of my second command set",
   };
   
   // Add or update all command sets with a single call
   await DragonCopilotSDK.dragon.applicationCommands.addOrUpdateCommandSets([myCommandSet1, myCommandSet2]);
   

2. Add or update your application commands, including the command set IDs:

   // Simple command
   const insertReportUrlCommand =
   {
     commandSetId: "cmdSet1",
     id: "insert-report-url",
     variants: [
       { spokenForm: "insert report", displayString: "Insert Report" },
     ],
     description: "Insert report URL",
   };
   
   // Command with standard placeholder
   const setNumberCommand =
   {
     commandSetId: "cmdSet1",
     id: "set-number",
     variants: [
       {
         spokenForm: "set number to <standard:cardinal0-100>",
         displayString: "Set number to <standard:cardinal0-100>",
       },
     ],
     description: "Set number using standard placeholder",
   };
   
   // Command with custom placeholder
   const setColorCommand =
   {
     commandSetId: "cmdSet1",
     id: "set-color",
     variants: [
       {
         spokenForm: "set color to <colorValue>",
         displayString: "Set color to <colorValue>",
       },
     ],
     description: "Set color using custom placeholder",
   };
   
   // Command with multiple variants
   const goHomeCommand =
   {
     commandSetId: "cmdSet1",
     id: "go-home",
     variants: [
       { spokenForm: "go home", displayString: "Go Home" },
       { spokenForm: "navigate home", displayString: "Navigate Home" },
     ],
     description: "Navigate to home page",
   };
   
   // Add or update all commands with a single call
   await DragonCopilotSDK.dragon.applicationCommands.addOrUpdateCommands([insertReportUrlCommand, setNumberCommand, setColorCommand, goHomeCommand]);
   

Command properties

Recommendations for the spoken form

Make sure you specify a spoken form that's unique, unambiguous and easy for your users to remember and pronounce.

When you enter the spoken form, follow these guidelines:

• Use alphabetic characters and single spaces only. Don't use:

  Digits (for example, use 'twelve' instead of '12') unless they're part of common words (for example, use '3D' instead of 'three D').

  Punctuation marks (for example, ., ", ! or ?).

  Symbols (for example, +, & or $) except for hyphens used in compound words (for example, 'C-spine').

  Double spaces.

• Follow standard capitalization rules (for example, use capital letters for proper names).

• Avoid using capital letters (except for acronyms or if the standard capitalization rules require it, see above).

• For acronyms that are spelled out, use capital letters (for example, CIA); if they're not recognized, separate the capital letters by spaces (for example, C I A).

• For acronyms that are pronounced as words, use lowercase (for example, use 'pet CT' for 'PETCT' or 'pick' for 'PICC').

• Don't use very short spoken forms that are acoustically difficult to capture (such as one syllable only). Very short spoken forms can lead to false positives.

• Use full words instead of abbreviations (for example, use 'without' instead of 'wo').

• Check for typos.

Capture text selection when a command is recognized

To capture the text selection when an application command is recognized, add the doCaptureSelection: true property to your command when you add or update it. The captured information is then provided in the selection property of the commandRecognized event.

By using this property, you can pass the selection's text value to other processes or alter the UI based on the selection start and length.

By default, doCaptureSelection is false and the user's text selection isn't captured.

Execute application commands synchronously

By default, when Dragon Copilot recognizes an application command, speech recognition continues immediately. With synchronous execution, recognition pauses after Dragon Copilot recognizes the command, giving your app time to perform actions (for example, update the UI or modify text) before resuming.

To enable synchronous execution, set isSynchronousExecution: true when you define the command. Once set, you can't change this property after you create the command.

When Dragon Copilot recognizes the command, the SDK raises the commandRecognized event. After your app completes all required actions (focus changes, text updates, selection changes), call completeCommand to resume recognition.

// Define a command with synchronous execution enabled
const insertTemplateCommand = {
  commandSetId: "cmdSet1",
  id: "insert-template",
  variants: [
    { spokenForm: "insert template", displayString: "Insert Template" },
  ],
  isSynchronousExecution: true,
  description: "Insert a template with paused recognition",
};

await DragonCopilotSDK.dragon.applicationCommands.addOrUpdateCommands([insertTemplateCommand]);

// Handle the command when recognized — recognition pauses until you call completeCommand
DragonCopilotSDK.dragon.applicationCommands.events.addEventListener(
  "commandRecognized",
  async (event: CustomEvent<CommandRecognizedEventDetail>) => {
    if (event.detail.commandId === "insert-template") {
      // Perform integrator actions (insert content, update focus, etc.)

      // Resume recognition after applying all changes
      await DragonCopilotSDK.dragon.applicationCommands.completeCommand(event.detail.commandId);
    }
  }
);

Placeholders

Application commands can include placeholders. The values for the placeholders need to be added by your app programmatically. Placeholders are displayed to the user as a single word in angled brackets. The displayed string can be different from the placeholder ID used in the command phrase.

The following types of placeholder are available:

• Standard placeholders delivered with Dragon Copilot: These placeholders are prefixed with standard. For example, show lab results from <standard:date>.

• Custom placeholders: For example, you define the placeholder <patient> with the values "Mr. Pink", "Mr. Orange", "Mr. Blue", "Mr. Purple", "Mr. Green"; you set the values dynamically at runtime. The user says show lab results for mister pink.

The app receives the values for all placeholders used within a command through the command's event.

Standard placeholders

Dragon Copilot provides standard placeholders out of the box. To add a standard placeholder to an application command, add its identifier to the command's spoken form and display string. If the command has a display string, the placeholder in the display string and in the spoken form must be the same.

The following standard placeholders are available:

Custom placeholders

To define your own placeholders programmatically:

// Define a placeholder
const placeholder: CommandPlaceholder = {
  id: "my-placeholders",
  label: "My Custom Placeholder",
  placeholderValues: [
    { value: "patient", spokenForm: "patient" },
    { value: "file", spokenForm: "file" },
    { value: "open", spokenForm: "open" },
  ],
};

await DragonCopilotSDK.dragon.applicationCommands.addOrUpdateCommandPlaceholders([placeholder]);

// Define a simple command that uses the placeholder
let simpleCommand: Command = {
  commandSetId: "cmdSet1",
  id: "placeholder-command",
  variants: [
    {
      spokenForm: `modify <${placeholder.id}>`,
      displayString: `Modify <${placeholder.label}>`,
    },
  ],
  isSynchronousExecution: false,
  description: `modify <${placeholder.label}>`,
};

// Apply the update
await DragonCopilotSDK.dragon.applicationCommands.addOrUpdateCommands([simpleCommand]);

Command recognized event

After adding or updating commands and command placeholders, it's important to register an event listener for the commandRecognized event. This listener enables your application to process commands when they're recognized.

// Registers an event listener for the commandRecognized event
DragonCopilotSDK.dragon.applicationCommands.events.addEventListener(
  "commandRecognized",
  (event: CustomEvent<CommandRecognizedEventDetail>) => {
    if (event.detail.commandId === "my-command-id") {
      // Handling logic for when `my-command` is triggered --------

    }
  }
);

Programmatically queue a command for execution

You can programmatically queue an application command to insert content in the document mid-stream during dictation, such as a link or information from a template. When you queue a command, the current utterance breaks. Once Dragon Copilot recognizes the preceding audio, the SDK triggers the commandRecognized event, allowing your app to insert the desired content into the document. After you make the necessary changes, call completeCommand to resume recognition.

// Registers an event listener for the commandRecognized event
DragonCopilotSDK.dragon.applicationCommands.events.addEventListener(
  "commandRecognized",
  async (event: CustomEvent<CommandRecognizedEventDetail>) => {
    if (event.detail.commandId === "insert-report-url") {
      // Insert report url...

      // Once insertion is complete, inform Dragon Copilot SDK
      await DragonCopilotSDK.dragon.applicationCommands.completeCommand(event.detail.commandId);
    }
  }
);

// Queue 'insert report' command when the button is clicked
insertReportButton.addEventListener("click", async () => {
  await DragonCopilotSDK.dragon.applicationCommands.queueCommand("insert-report-url");
});

See also

API reference