Integration guide
The Dictation SDK allows you to embed Invox Medical's voice dictation capabilities directly into your web application. This guide walks you through the complete setup, from downloading the SDK files to handling your first recognized text.
Prerequisites
Before you begin, make sure you have the following:
- Dictation Service credentials — a username and password assigned to your organization. Contact support if you do not have them yet.
- A modern browser with microphone support (see General Considerations for the full compatibility list).
Step 1 — Download the SDK
Download the latest SDK package from the Invox Medical SDK Portal:
The package contains the following structure:
libs/
├── invox.min.js ← Core SDK (required)
├── integrations/
│ ├── invox-bar/
│ │ ├── invox-bar-component.css ← INVOX Bar styles
│ │ └── invox-bar-component.min.js ← INVOX Bar component
│ └── invox-dialogs/
│ ├── invox-dictionary-component.css
│ ├── invox-dictionary-component.min.js
│ ├── invox-templates-component.css
│ ├── invox-templates-component.min.js
│ ├── invox-transformations-component.css
│ └── invox-transformations-component.min.js
└── opus/ ← Audio codec resources (required)
Copy the libs/ folder into your project's static assets directory.
Step 2 — Include the SDK files
Add the required scripts and stylesheets to your HTML page. At minimum, include the core SDK and the INVOX Bar integration.
<!-- Core SDK — Required -->
<script type="text/javascript" src="libs/invox.min.js" charset="UTF-8"></script>
<!-- INVOX Bar — Required for the standard dictation toolbar -->
<link rel="stylesheet" href="libs/integrations/invox-bar/invox-bar-component.css">
<script type="text/javascript" src="libs/integrations/invox-bar/invox-bar-component.min.js" charset="UTF-8"></script>
Optional modules
Include these only if your integration uses the corresponding features:
<!-- Dictionary component -->
<link rel="stylesheet" href="libs/integrations/invox-dialogs/invox-dictionary-component.css">
<script type="text/javascript" src="libs/integrations/invox-dialogs/invox-dictionary-component.min.js" charset="UTF-8"></script>
<!-- Templates component -->
<link rel="stylesheet" href="libs/integrations/invox-dialogs/invox-templates-component.css">
<script type="text/javascript" src="libs/integrations/invox-dialogs/invox-templates-component.min.js" charset="UTF-8"></script>
<!-- Transformations component -->
<link rel="stylesheet" href="libs/integrations/invox-dialogs/invox-transformations-component.css">
<script type="text/javascript" src="libs/integrations/invox-dialogs/invox-transformations-component.min.js" charset="UTF-8"></script>
The
libs/opus/ folder must remain co-located with invox.min.js. The SDK loads the audio codec from that path automatically when connecting to the Remote Dictation Service.Step 3 — Add the required HTML elements
The SDK requires specific elements to be present in the DOM before initialization.
<!-- Dictation Bar container — rendered inside this element -->
<div id="invox-bar"></div>
<!-- Writer target — the text field that receives dictated text -->
<textarea id="my-editor"></textarea>
<!-- Toast notification container — displays SDK status messages -->
<div id="invox-toast-stack-container" class="toast-container position-fixed bottom-0 end-0 p-3">
<div class="toast border-0 invox-hide" role="alert" aria-live="assertive" aria-atomic="true" invox-toast="stack">
<div class="toast-header text-white invox-toast-border-rounded" style="min-height: 55px;">
<i class="bi invox-toast-icon me-1"></i>
<span class="invox-toast-message me-auto px-2"></span>
<button class="btn-close btn-close-white me-1" data-bs-dismiss="toast" aria-label="Close"></button>
</div>
</div>
</div>
The id values invox-bar and invox-toast-stack-container are required by the SDK. The writer target element (my-editor in the example above) can use any id of your choice.
Step 4 — Initialize the SDK
All initialization must happen inside the window load event. Follow the exact order below:
- Set the language — determines the dictation language and SDK UI locale.
- Register component callbacks — done inside
INVOX.CustomizeComponents(), which must be called beforeINVOX.Login(). - Create and show the INVOX Bar — the pre-built dictation toolbar.
- Listen for login events — set the writer target after a successful connection.
- Login — connect to the Dictation Service.
window.addEventListener('load', function () {
// 1. Set the dictation language
INVOX.SetLang(INVOX.LangEnum.en_US);
// 2. Register all callbacks before login
INVOX.CustomizeComponents(function () {
INVOX.OnChangeStatusBar(function (msg, type) {
console.log(`[${type}] ${msg}`);
});
INVOX.OnRunningRecognizer(function () {
console.log('Dictation is active');
});
INVOX.OnPausedRecognizer(function () {
console.log('Dictation is paused');
});
INVOX.OnGrantedAudioSource(function () {
console.log('Microphone access granted:', INVOX.GetMicrophoneName());
});
INVOX.OnDeniedAudioSource(function () {
console.warn('Microphone access denied');
INVOX.SetDictationPaused();
});
});
// 3. Create and show the Dictation Bar
const invoxBar = INVOXMDComponent_Bar.create('invox-bar');
invoxBar.show();
// 4. Listen for login result events
document.addEventListener(INVOX.eventTypeReport.LOGIN_SUCCESS, function () {
// Set the writer target once connected
INVOX.SetTextWriter(INVOX.TextAreaTextWriter);
INVOX.SetWriterTarget(document.getElementById('my-editor'));
});
document.addEventListener(INVOX.eventTypeReport.LOGIN_ERROR, function (e) {
console.error('Login failed:', e.detail);
});
// 5. Login with your credentials and service configuration
invoxBar.login(
{ user: 'your-username', password: 'your-password' },
{ host: 'your-host.invoxmedical.com', port: 8443, useDictationService: true }
);
});
INVOX.CustomizeComponents()must always be called beforeINVOX.Login() or invoxBar.login(). Reversing this order will fire a NOT_CUSTOMIZED_COMPONENTS event and callbacks will not be bound correctly.Step 5 — Handle logout
To end the session and release microphone resources:
invoxBar.logout()
.then(() => console.log('Session ended'))
.catch((e) => console.error(e));