Essential Functions
Use these functions in order: initialize the SDK, register component callbacks, log in, select a writer target, and control dictation.
init
INVOX.init(config) stores the SDK configuration required by Login.
organizationId, appId, and apiKey are provided by Invox Medical for your integration. Use the exact values you receive; do not choose your own.
organizationId:String— required. Identifier of your organization in Corporate Server. It contains only lowercase letters, digits, and hyphens. Requests are routed to/<organizationId>/EasyDictation.appId:String— required. Identifier of the application that integrates the SDK.apiKey:String— required. API key associated withappId.adminServiceUrl:String— optional. Base URL of the Corporate Server used for authentication and user data. If omitted, the SDK uses the Invox Medical Corporate Server. Provide it only when your organization uses its own Corporate Server installation, or when requests go through a proxy of your application; Invox Medical provides the URL in that case.wakeWordAssetBaseUrl:String— optional. URL of the folder that contains the deployedwake-word-assets(wake-word models and WASM runtime). If omitted, the SDK looks for awake-word-assets/folder next to the SDK bundle. Provide it only if your integration uses wake-word detection and you publish that folder in another location of the same origin, for example/assets/wake-word-assets/.
import INVOX, {
type InitializationConfigType,
} from "@invox-medical-npm/invox-dictation";
const config: InitializationConfigType = {
organizationId: "provided-organization-id",
appId: "provided_app_id",
apiKey: "provided_api_key",
// Only if your organization uses its own Corporate Server:
// adminServiceUrl: "provided_admin_service_url",
// Only if wake-word assets are not deployed next to the SDK bundle:
// wakeWordAssetBaseUrl: "/assets/wake-word-assets/",
};
INVOX.init(config);
The Direct Dictation endpoint is selected by the SDK build. transcriptionServiceUrl is not accepted by this API.
CustomizeComponents
Register a callback before Login. The SDK invokes it after the session has been created so the callback can register component and recognizer callbacks.
INVOX.CustomizeComponents(() => {
INVOX.OnChangeStatusBar((status) => {
updateStatus(status);
});
});
Calling Login without registering CustomizeComponents fails.
Login
INVOX.Login(credentials) authenticates with Corporate Server, imports the post-authentication data, creates the SDK session, and starts Direct Dictation. It returns Promise<void> and rejects when authentication or session setup fails.
import type { LoginCredentialsType } from "@invox-medical-npm/invox-dictation";
const credentials: LoginCredentialsType = {
user: "provided_username",
password: "provided_password",
};
try {
await INVOX.Login(credentials);
} catch (error) {
console.error("Login failed.", error);
}
Login errors
When Login fails, the promise rejects with an InvoxLoginError (from version 2.9.38; earlier releases reject with the internal client error). Its message is already translated to the SDK language (es-ES, en-US, pt-PT or pt-BR), so you can show it to the user as is; String(error) returns that same text. The message never contains the server response, URLs, the user or the password. For a wrong user or password it is the same whatever the server answered, so it does not reveal whether the user exists.
| Property | Description |
|---|---|
name | "InvoxLoginError". |
message | Translated text to show to the user. |
code | Stable identifier of the cause (table below). Branch on it, not on the message. |
httpStatus | HTTP status of the failed request (0 for a network failure or timeout of the Corporate Server, or when the token check fails (see LOGIN_AUTHORIZATION_REJECTED and LOGIN_SERVICE_UNAVAILABLE); 200 for an unreadable answer from the server). |
exceptionType | Exception type of the failure, with the same values as in previous releases. |
code | When (HTTP status) |
|---|---|
INVALID_CREDENTIALS | 403 |
CONNECTION_ERROR | Network failure or timeout (0), 407, 5xx, and a 5xx while importing the user data after a valid login |
INVALID_LICENSE | 412 |
CONCURRENT_LICENSE | 413 |
LDAP_INVALID_USER | 414 |
LDAP_NO_SPECIALTY | 415 |
DUPLICATE_SESSION | 409 |
LOGIN_AUTHORIZATION_REJECTED | The token server answers 401 or 403: the credential (appId and apiKey) is rejected or does not belong to organizationId. Not an SC call: httpStatus 0, exceptionType UNKNOWN |
LOGIN_SERVICE_UNAVAILABLE | Any other token failure: another HTTP status (for example 500), no answer within 15 seconds, or a network error. Not an SC call: httpStatus 0, exceptionType UNKNOWN |
LOGIN_FAILED | Any other status (405, 404 unknown organization, ...), a 403 while importing the user data after a valid login, and an unreadable answer from the server (HTTP 200 that is not the expected JSON; httpStatus 200, exceptionType UNKNOWN) |
try {
await INVOX.Login(credentials);
} catch (error) {
showLoginError(error.message);
if (error.code === "INVALID_CREDENTIALS") {
focusPasswordField();
}
}
Misuse errors (INVOX.init not called, empty credentials, CustomizeComponents missing) remain plain Error. InvoxLoginError is exported as a TypeScript type only, so check error.code rather than using instanceof.
Logout
INVOX.Logout() closes the current session. It returns Promise<boolean>; a resolved value of true confirms the close operation completed. Intentional logout also emits LOGGING_OUT.
const loggedOut = await INVOX.Logout();
if (loggedOut) {
clearDictationUi();
}
Dictation controls
INVOX.SwitchDictation() changes between the running and paused recognizer states. INVOX.SetDictationRunning() and INVOX.SetDictationPaused() set an explicit state.
INVOX.SwitchDictation();
Writer target
Set a writer implementation and an editor target after a successful login. The public writer methods receive an editorInstance; pass the same target used by SetWriterTarget when invoking them directly.
const report = document.querySelector<HTMLTextAreaElement>("#report");
if (!report) {
throw new Error("Report textarea is missing.");
}
INVOX.SetTextWriter(INVOX.TextAreaTextWriter);
INVOX.SetWriterTarget(report);
const target = await INVOX.GetWriterTarget();
See Writer Functions for Write, AppendText, selection, and synchronous or asynchronous writer behavior.