Invox Dictation SDK Version:

Quick Start

This guide connects a web application to Invox Dictation through Corporate Server and starts dictation in a textarea. Install the package first, then use your bundler to resolve the SDK import.

For a ready-made interface, use the Quick Integration Components. The flow below is for a custom integration.

Create the target

<textarea id="report" placeholder="Recognized text"></textarea>
<button id="login">Log in</button>
<button id="dictation" disabled>Start or stop dictation</button>
<button id="logout" disabled>Log out</button>

Initialize and customize

Create src/main.ts in an application built with Vite or an equivalent bundler.

import INVOX from "@invox-medical-npm/invox-dictation";

const report = document.querySelector<HTMLTextAreaElement>("#report");
const loginButton = document.querySelector<HTMLButtonElement>("#login");
const dictationButton = document.querySelector<HTMLButtonElement>("#dictation");
const logoutButton = document.querySelector<HTMLButtonElement>("#logout");

if (!report || !loginButton || !dictationButton || !logoutButton) {
  throw new Error("Required controls are missing.");
}

INVOX.init({
  organizationId: "provided-organization-id",
  appId: "provided_app_id",
  apiKey: "provided_api_key",
  // adminServiceUrl: "provided_admin_service_url",
  // wakeWordAssetBaseUrl: "/assets/wake-word-assets/",
});

INVOX.CustomizeComponents(() => {
  INVOX.OnReconnectingRecognizer(() => {
    dictationButton.textContent = "Reconnecting...";
    dictationButton.disabled = true;
  });

  INVOX.OnRunningRecognizer(() => {
    dictationButton.textContent = "Start or stop dictation";
    dictationButton.disabled = false;
  });
});

All values are provided by Invox Medical for your integration:

  • organizationId (required): identifier of your organization in Corporate Server. Lowercase letters, digits, and hyphens only.
  • appId (required): identifier of the application that integrates the SDK.
  • apiKey (required): API key associated with appId.
  • adminServiceUrl (optional): Corporate Server URL. If omitted, the SDK uses the Invox Medical Corporate Server. Set it only when your organization uses its own Corporate Server or a proxy of your application.
  • wakeWordAssetBaseUrl (optional): location of the wake-word-assets folder. If omitted, the SDK looks for it next to the SDK bundle. Set it only if you use wake-word detection and publish that folder elsewhere on the same origin.

Do not provide transcriptionServiceUrl: Direct Dictation routing is selected by the SDK build. See init for details.

Log in and configure the writer

Register CustomizeComponents before Login. The SDK rejects login if no component customization callback has been registered.

loginButton.addEventListener("click", async () => {
  try {
    await INVOX.Login({
      user: "provided_username",
      password: "provided_password",
    });

    INVOX.SetTextWriter(INVOX.TextAreaTextWriter);
    INVOX.SetWriterTarget(report);
    dictationButton.disabled = false;
    logoutButton.disabled = false;
  } catch (error) {
    console.error("Could not start the dictation session.", error);
  }
});

Login authenticates with Corporate Server, imports the user data, then starts Direct Dictation. Credentials are not sent to the Direct Dictation endpoint.

Start, stop, and close the session

dictationButton.addEventListener("click", () => {
  INVOX.SwitchDictation();
});

logoutButton.addEventListener("click", async () => {
  const loggedOut = await INVOX.Logout();
  if (loggedOut) {
    dictationButton.disabled = true;
    logoutButton.disabled = true;
  }
});

document.addEventListener(INVOX.eventTypeReport.LOGIN_ERROR, (event) => {
  console.error(event.detail);
  dictationButton.disabled = true;
  logoutButton.disabled = true;
});

See Session Management for automatic ASR reconnection and the cases that require a new login.

Table of Contents