Quick Start

Introduction

To perform an agile and effortless deployment, check out the Quick Integration Components. These web components integrate the full functionality of the API along with a user interface that enables interaction with the system.

The Invox Dictation SDK offers essential functionalities for user authentication, speech recognition initiation and termination, and configuring the editor to display the results of speech recognition. For detailed information on these functions, please refer to the JavaScript API documentation.

This section will guide you through the development of the essential functionality required to establish a connection with the dictation service, perform dictation, and display the results in a text editor.

Integration Scenarios

Depending on your specific deployment needs, you have the flexibility to use either one or both services for testing and developing your integration. For more information on the available options, please refer to the Integration Scenarios section.

Folder Structure

The folder and file structure for this example is straightforward. Create a root folder named invox-quick-start that includes the following files:

.
|-- invox-quick-start/
    |-- opus/                 <- Opus Audio Library required for Remote Dictation Service
    |-- invox.min.js
    |-- index.html

The crucial aspect is to have the opus/ folder and its content at the same level as the invox.min.js file. Please remember to include this audio library in order to connect to the Remote Dictation Service.
The full code of this example will be located in the index.html file.

Full Code

The following code includes all the necessary components to execute the example:

<!DOCTYPE html>
<html lang="EN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <meta http-equiv='cache-control' content='no-cache'>
    <meta http-equiv='expires' content='0'>
    <meta http-equiv='pragma' content='no-cache'>

    <!-- Invox Dictation SDK-->
    <script type="text/javascript" src="invox.min.js" charset="UTF-8"></script>

    <!-- Bootstrap -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" >
</head>
<body>
    <main class="m-2">
        <button class="btn btn-primary" onclick="DoLogin()">Login</button>
        <button class="btn btn-secondary" onclick="DoLogout()">Logout</button>
        <button class="btn btn-danger" onclick="SwitchDictation()">Switch Dictation</button>
        <textarea id="invox-textarea-1" class="form-control mt-2" placeholder="Recognized text..."></textarea>
    </main>
    <script>
        async function DoLogin() {
            const credentials = {
                user: "provided_username",
                password: "provided_password"
            }

            const connectToLocal = {
                host: "localhost",
                port: "8443",
                useDictationService: false
            }

            const connectToRemote = {
                host: "dev.invoxmedical.com/v2.8.3",
                port: "8443",
                useDictationService: true
            }

            try {
                await INVOX.Login(credentials, connectToLocal);
                INVOX.LogInfo("Local Dictation Service connected successfully.");
            } catch (error) {
                INVOX.LogWarn("Local Dictation Service not found. Trying to connect to Remote Dictation Service...");
                try {
                    await INVOX.Login(credentials, connectToRemote);
                    INVOX.LogInfo("Remote Dictation Service connected successfully.");
                } catch (error) {
                    INVOX.LogError("Remote Dictation Service not found. Make sure that connection parameters are correct.");
                }
            }
        }

        async function DoLogout() {
            try {
                await INVOX.Logout()
                INVOX.LogInfo("Session closed successfully")
            } catch(error) {
                INVOX.LogError(error.message)
            }
        }

        function SwitchDictation() {
            try {
                INVOX.SwitchDictation()
            } catch(error) {
                INVOX.LogError(error.message)
            }
        }

        document.addEventListener(INVOX.eventTypeReport.LOGIN_ERROR, (event) => {
            INVOX.LogError(event.detail)
            alert(event.detail)
        })

        document.addEventListener(INVOX.eventTypeReport.LOGIN_SUCCESS, (event) => {
            INVOX.LogInfo(event.detail)
            try {
                INVOX.SetTextWriter(INVOX.TextAreaTextWriter)
                const textareaElement = document.getElementById("invox-textarea-1")
                INVOX.SetWriterTarget(textareaElement)
            } catch(error) {
                INVOX.LogError(error.message)
            }
        })

        document.addEventListener(INVOX.eventTypeReport.NOT_CUSTOMIZED_COMPONENTS, (event) => {
            INVOX.LogWarn(event.detail)
        })
    </script>
</body>
</html>

Installation

First, create a new project and install the SDK:

mkdir invox-quick-start
cd invox-quick-start
npm init -y
npm install @invox-medical-npm/invox-dictation

Folder Structure

The folder and file structure for this example is straightforward:

.
|-- invox-quick-start/
    |-- node_modules/
    |-- package.json
    |-- index.html

The full code of this example will be located in the index.html file.

Full Code

The following code includes all the necessary components to execute the example:

<!DOCTYPE html>
<html lang="EN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
    <meta http-equiv='cache-control' content='no-cache'>
    <meta http-equiv='expires' content='0'>
    <meta http-equiv='pragma' content='no-cache'>

    <!-- Bootstrap -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" >
    <script type="module">
        import INVOX from "@invox-medical-npm/invox-dictation";

        INVOX.init({
            transcriptionServiceUrl: "wss://dev.invoxmedical.com/v2.9",
            adminServiceUrl: "https://dev.invoxmedical.com/",
            organizationId: "provided_organization_id",
            appId: "provided_app_id",
            apiKey: "provided_api_key",
        });

        async function DoLogin() {
            const credentials = {
                user: "provided_username",
                password: "provided_password"
            }

            try {
                await INVOX.Login(credentials);
                INVOX.LogInfo("Remote Dictation Service connected successfully.");
            } catch (error) {
                INVOX.LogError("Remote Dictation Service not found. Make sure that initialization parameters are correct.");
            }
        }

        async function DoLogout() {
            try {
                await INVOX.Logout()
                INVOX.LogInfo("Session closed successfully")
            } catch(error) {
                INVOX.LogError(error.message)
            }
        }

        function SwitchDictation() {
            try {
                INVOX.SwitchDictation()
            } catch(error) {
                INVOX.LogError(error.message)
            }
        }

        document.addEventListener(INVOX.eventTypeReport.LOGIN_ERROR, (event) => {
            INVOX.LogError(event.detail)
            alert(event.detail)
        })

        document.addEventListener(INVOX.eventTypeReport.LOGIN_SUCCESS, (event) => {
            INVOX.LogInfo(event.detail)
            try {
                INVOX.SetTextWriter(INVOX.TextAreaTextWriter)
                const textareaElement = document.getElementById("invox-textarea-1")
                INVOX.SetWriterTarget(textareaElement)
            } catch(error) {
                INVOX.LogError(error.message)
            }
        })

        document.addEventListener(INVOX.eventTypeReport.NOT_CUSTOMIZED_COMPONENTS, (event) => {
            INVOX.LogWarn(event.detail)
        })
    </script>
</head>
<body>
    <main class="m-2">
        <button class="btn btn-primary" onclick="DoLogin()">Login</button>
        <button class="btn btn-secondary" onclick="DoLogout()">Logout</button>
        <button class="btn btn-danger" onclick="SwitchDictation()">Switch Dictation</button>
        <textarea id="invox-textarea-1" class="form-control mt-2" placeholder="Recognized text..."></textarea>
    </main>
</body>
</html>

Import resources

After installing the SDK via npm, import it into your project using ES modules with a bundler (e.g., Vite) or a modern browser:

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

Component styles are auto-injected at runtime — no separate CSS imports are needed.

Log in

To initiate the login process, use the flow that matches your SDK version:

v2.9+: initialize the SDK with INVOX.init(...) and then pass credentials to Login.
v2.8: pass credentials and connection data directly to Login.

HTML

<button class="btn btn-primary" onclick="DoLogin()">Login</button>

JavaScript

The following code initializes SDK connection context and then connects to the Remote Dictation Service:

INVOX.init({
    organizationId: "provided_organization_id",
    appId: "provided_app_id",
    apiKey: "provided_api_key",
    // transcriptionServiceUrl: "provided_transcription_service_url",
    // adminServiceUrl: "provided_admin_service_url",
});

async function DoLogin() {
    const credentials = {
        user: "provided_username",
        password: "provided_password"
    }

    try {
        await INVOX.Login(credentials);
        INVOX.LogInfo("Remote Dictation Service connected successfully.");
    } catch (error) {
        INVOX.LogError("Remote Dictation Service not found. Make sure that credentials and initialization parameters are correct.");
    }
}

All INVOX.init values are provided by Invox Medical for your integration:

organizationId (required): identifier of your organization in Invox Medical.
appId (optional): identifier of the application that integrates the SDK. Provide it when Invox Medical has issued application credentials for your integration.
apiKey (optional): API key associated with appId. Provide it together with appId.
transcriptionServiceUrl (optional): URL of the Remote Dictation Service. If omitted, the SDK uses the debug environment wss://debug.invoxmedical.com. Set it whenever you connect to any other environment, such as UAT or production.
adminServiceUrl (optional): URL of the Corporate Server used for authentication. If omitted, the SDK uses the debug environment https://debug.invoxmedical.com/INVOX/. Set it whenever you connect to any other environment, such as UAT or production.

See init for details.

document.addEventListener(INVOX.eventTypeReport.LOGIN_ERROR, (event) => {
    INVOX.LogError(event.detail)
    alert(event.detail)
})

document.addEventListener(INVOX.eventTypeReport.LOGIN_SUCCESS, (event) => {
    INVOX.LogInfo(event.detail)
})

document.addEventListener(INVOX.eventTypeReport.NOT_CUSTOMIZED_COMPONENTS, (event) => {
    INVOX.LogWarn(event.detail)
})

Set writing location

It is crucial to configure the Writer after a successful login, using the promise returned by Login or by handling the LOGIN_SUCCESS event.

HTML

TextArea Target

<textarea id="invox-textarea-1" class="form-control" placeholder="Recognized text..."></textarea>

JavaScript

document.addEventListener(INVOX.eventTypeReport.LOGIN_SUCCESS, () => {
    try {
        INVOX.SetTextWriter(INVOX.TextAreaTextWriter)
        const textareaElement = document.getElementById("invox-textarea-1")
        INVOX.SetWriterTarget(textareaElement)
    } catch(error) {
        INVOX.LogError(error.message)
    }
})

Start or stop speech recognition

HTML

<button class="btn btn-danger" onclick="SwitchDictation()">Switch Dictation</button>

JavaScript

function SwitchDictation() {
    try {
        INVOX.SwitchDictation()
    } catch(error) {
        INVOX.LogError(error.message)
    }
}

Log out

HTML

<button class="btn btn-secondary" onclick="DoLogout()">Logout</button>

JavaScript

async function DoLogout() {
    try {
        await INVOX.Logout()
        INVOX.LogInfo("Session closed successfully")
    } catch(error) {
        INVOX.LogError(error.message)
    }
}

Getting StartedDocker deployment examples

Getting StartedUpgrade Guide