Commands is a key functionality that brings the system beyond speech-to-text to a complete dictation solution. Put your users in the driver seat to control their workflow by defining commands to insert templates, navigate the application, automate repetitive tasks, and more!
Below are some example commands, but see the full API specification here for more information on how to define commands in your configuration.

​
Command definition and examples

Below are example commands you can use in your dictation configuration when directly calling the /transcribe API or when using the Dictation SDK. The command ID will be returned in the dictation results stream for the integrating application to use for executing the expected action.

​
Go to section

Command to navigate to a section within the current document. The command includes a defined list of words that can be recognized for the section_key variable.
Go to section command
commands: [
    {
      id: "go_to_section",
      phrases: ["go to {section_key} section"],
      variables: [
        {
          key: "section_key",
          type: "enum",
          enum: ["subjective", "objective", "assessment", "plan", "next", "previous"]
        }
      ]
    }
]

​
Delete text

Command to delete text. The command includes a defined list of words that can be recognized for the delete_range variable. Your application can define different delete actions for each of the options!
Delete text command
commands: [
    {
      id: "delete_range",
      phrases: ["delete {delete_range}"],
      variables: [
        {
          key: "delete_range",
          type: "enum",
          enum: ["everything", "the last word", "the last sentence", "that"]
        }
      ]
    }
]

​
Select text

Command to select text in the editor. The command includes a defined list of words that can be recognized for the select_range variable. Your application can define different delete actions for each of the options, or add more complex handling for selecting specific words mentioned in the command utterance.
Select text command
commands: [
    {
      id: "select_range",
      phrases: ["select {select_range}"],
      variables: [
        {
          key: "select_range",
          type: "enum",
          enum: ["everything", "the last word", "the last sentence"]
        }
      ]
    }
  ]

​
Putting it all together

The three commands defined above can be combined into one dictation configuration with accompanying Javascript to execute the actions:
Full Dictation Command Configuration
dictation.dictationConfig = {
  primaryLanguage: "en",
  interimResults: true,
  spokenPunctuation: true,
  automaticPunctuation: false,
  model: "premier",
  commands: [
    {
      id: "go_to_section",
      phrases: ["go to {section_key} section"],
      variables: [
        {
          key: "section_key",
          type: "enum",
          enum: ["subjective", "objective", "assessment", "plan", "next", "previous"]
        }
      ]
    },
    {
      id: "delete_range",
      phrases: ["delete {delete_range}"],
      variables: [
        {
          key: "delete_range",
          type: "enum",
          enum: ["everything", "the last word", "the last sentence", "that"]
        }
      ]
    },
    {
      id: "select_range",
      phrases: ["select {select_range}"],
      variables: [
        {
          key: "select_range",
          type: "enum",
          enum: ["everything", "the last word", "the last sentence"]
        }
      ]
    }
  ]
};

dictation.addEventListener("transcript", (e) => {
  const { data } = e.detail;
  const currentTextarea = textareas[activeIndex];
  const interimTranscriptEl = document.getElementById("interimTranscript");

  if (data.isFinal) {
    // Instead of appending at the end, insert the text at the user's cursor
    // or replace the selected range.
    const start = currentTextarea.selectionStart;
    const end = currentTextarea.selectionEnd;
    const insertedText = data.text + " ";
    const before = currentTextarea.value.slice(0, start);
    const after = currentTextarea.value.slice(end);
    currentTextarea.value = before + insertedText + after;
    const newCursorPos = start + insertedText.length;
    currentTextarea.setSelectionRange(newCursorPos, newCursorPos);
    
    interimTranscriptEl.classList.add("hidden");
  } else {
    interimTranscriptEl.classList.remove("hidden");
    interimTranscriptEl.innerText = data.rawTranscriptText;
  }
});

dictation.addEventListener("command", (e) => {
  const { data } = e.detail;
  document.getElementById("interimTranscript").classList.add("hidden");
  const commandOutput = document.getElementById("commandOutput");

  if (data.id === "go_to_section") {
    const section = data.variables.section_key.toLowerCase();
    if (section === "next") {
      if (activeIndex < textareas.length - 1) {
        activeIndex++;
        textareas[activeIndex].focus();
      }
    } else if (section === "previous") {
      if (activeIndex > 0) {
        activeIndex--;
        textareas[activeIndex].focus();
      }
    } else {
      const index = textareas.findIndex(el => el.id.toLowerCase() === section);
      if (index !== -1) {
        activeIndex = index;
        textareas[activeIndex].focus();
      }
    }
    commandOutput.innerHTML = "Command: " + data.id + " with section key: " + section;

  } else if (data.id === "delete_range") {
    const range = data.variables.delete_range.toLowerCase();
    const currentTextarea = textareas[activeIndex];
    let content = currentTextarea.value;
    
    if (range === "everything") {
      currentTextarea.value = "";
    } else if (range === "the last word") {
      let words = content.trim().split(/\s+/);
      words.pop();
      currentTextarea.value = words.join(" ") + (words.length > 0 ? " " : "");
    } else if (range === "the last sentence") {
      let sentences = content.match(/[^.!?]+[.!?]*\s*/g);
      if (sentences && sentences.length > 0) {
        sentences.pop();
        currentTextarea.value = sentences.join("");
      }
    } else if (range === "that") {
      // If there's a selection, delete it; otherwise, delete the last word.
      const start = currentTextarea.selectionStart;
      const end = currentTextarea.selectionEnd;
      if (start !== end) {
        currentTextarea.value = content.slice(0, start) + content.slice(end);
      } else {
        let words = content.trim().split(/\s+/);
        words.pop();
        currentTextarea.value = words.join(" ") + (words.length > 0 ? " " : "");
      }
    }
    commandOutput.innerHTML = "Command: " + data.id + " with delete range: " + range;

  } else if (data.id === "select_range") {
    const range = data.variables.select_range.toLowerCase();
    const currentTextarea = textareas[activeIndex];
    const content = currentTextarea.value;
    
    if (range === "everything") {
      currentTextarea.focus();
      currentTextarea.setSelectionRange(0, content.length);
    } else if (range === "the last word") {
      const trimmedContent = content.trimEnd();
      const lastSpaceIndex = trimmedContent.lastIndexOf(" ");
      const start = lastSpaceIndex !== -1 ? lastSpaceIndex + 1 : 0;
      currentTextarea.focus();
      currentTextarea.setSelectionRange(start, trimmedContent.length);
    } else if (range === "the last sentence") {
      const sentences = content.match(/[^.!?]+[.!?]*\s*/g);
      if (sentences && sentences.length > 0) {
        let sum = 0;
        for (let i = 0; i < sentences.length - 1; i++) {
          sum += sentences[i].length;
        }
        const lastSentence = sentences[sentences.length - 1];
        const start = sum;
        const end = start + lastSentence.length;
        currentTextarea.focus();
        currentTextarea.setSelectionRange(start, end);
      }
    }
    commandOutput.innerHTML = "Command: " + data.id + " with select range: " + range;
  }
});
Use of commands is optional for dictation configuration. They should be configured based on how the integrating application will perform the actions.Please contact us for more information on or help with building commands.