Dictation SDK Quickstart

This guide walks you through the steps to integrate the Dictation SDK into your application. What will you do

Install the Dictation SDK package for your framework (JavaScript or React)
Create a SukiAuthManager from @suki-sdk/core with your partnerToken and provider fields
Create a DictationClient from @suki-sdk/dictation with your auth manager
Mount the Dictation UI into your application using the encounter object.

Using an AI coding tool?Copy the following prompt to add the Suki developer documentation as a skill and MCP server to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, llms.txt, and skill.md), refer to AI-optimized documentation.

Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the MCP server for documentation search.

Open in Cursor

Prerequisites

Before you start, ensure you have the following:

You have received your partnerId and partnerToken from Suki.
Your app meets browser, CSP, and host requirements for the dictation iframe

Refer to Prerequisites for more details.

Recommended integration pattern

The Dictation SDK works best when you treat authentication and the dictation client as long-lived objects for a page or session. You should only change the specific field or surface receiving the dictation. This approach ensures that token refreshes and iframe setups remain predictable while avoiding duplicate overlays. A common mistake is to build a new DictationClient on every React render (for example, in the component body without useMemo) or to use a separate client for each text field. The SDK assumes one client per page scope. If you do not follow this pattern, the session and iframe will frequently tear down and restart. This creates an unstable experience for the user.

Initialize once per session and reuse:

Suki Auth Manager

Create SukiAuthManager from @suki-sdk/core after the partner token is available.

Dictation Client

Create DictationClient with that authManager. Reuse this client across dictation fields.

Dictation Provider (React only)

In React, wrap components with DictationProvider from @suki-sdk/dictation-react.

Dictation Per Active Field

Show the dictation UI per field or scratchpad. Avoid recreating DictationClient on every render or per field.

The JavaScript and React tabs under Your first dictation session below mirror this pattern: one auth manager, one client, then show() or <Dictation> for the active target only.

Field IDs

Each dictation instance needs a stable, unique fieldId. The SDK sends it back on every callback with text, so you can route results to the right control. A common pattern is to match the target input’s HTML id. Refer to Field IDs section in Configuration guide for more details.

Install the packages

JavaScript
React

pnpm add @suki-sdk/dictation @suki-sdk/core

npm install @suki-sdk/dictation @suki-sdk/core

yarn add @suki-sdk/dictation @suki-sdk/core

More detail: Installation.

pnpm add @suki-sdk/dictation-react @suki-sdk/core

npm install @suki-sdk/dictation-react @suki-sdk/core

yarn add @suki-sdk/dictation-react @suki-sdk/core

More detail: Installation.

Create your first dictation session

Apply Recommended integration pattern above: build SukiAuthManager and DictationClient once, then open dictation only for the target that should be active. For JavaScript, give dictation a container (rootElement) with real height. Example markup:

<div id="dictation-root"></div>
<textarea id="clinical-notes"></textarea>

JavaScript
React

Create the auth manager and client once, then call show() when the user should dictate (for example after a button click). Use try / catch so configuration or auth errors surface in your logs.

JavaScript

import { SukiAuthManager } from "@suki-sdk/core"; // Step 1: Create the auth manager
import { DictationClient } from "@suki-sdk/dictation"; // Step 2: Create the client

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
  partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
  environment: "staging", // optional - default is "production"
  loginOnInitialize: true, // optional - default is false
  providerName: "John doe", // optional - default is empty
  providerOrgId: "1234", // optional - default is empty
  providerId: "1234567890", // optional - default is empty
  providerSpecialty: "FAMILY_MEDICINE", // optional - default is empty
});

const client = new DictationClient({ authManager }); // Step 3: Create the client

async function startDictation() {
  try {
    await client.show({
      mode: "in-field", // required - you must set this as per your use case
      fieldId: "clinical-notes", // required - you must set this to the ID of the textarea you want to dictate
      rootElement: document.getElementById("dictation-root"), // required - you must set this to the ID of the div you want to contain the dictation iframe
      initialText:
        document.getElementById("clinical-notes")?.value ?? "", // optional - you can set this to the initial text of the textarea
      onSubmit: ({ fieldId, text }) => {
        const el = document.getElementById(fieldId);
        if (el) el.value = text;
      },
      onCancel: ({ fieldId }) => {
        console.log("Cancelled", fieldId);
      },
    });
  } catch (err) {
    console.error(err);
  }
}

// Call startDictation() from your UI when ready.

Your integration is working when the dictation UI appears inside dictation-root, you can dictate, and text you commit is written to the textarea in onSubmit.

For optional settings and callbacks (onDraft, initialText, scratchpad mode, and more), refer to Configuration. For iframe or layout problems, refer to Error handling guide for more details.

Create DictationClient once (useMemo), wrap the tree with DictationProvider, and render <Dictation> only when that field should own the session. Unmounting <Dictation> calls hide() for you.

React

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core"; // Step 1: Create the auth manager
import { DictationClient } from "@suki-sdk/dictation"; // Step 2: Create the client
import { DictationProvider, Dictation } from "@suki-sdk/dictation-react"; // Step 3: Wrap the tree with DictationProvider

export function NotesWithDictation() {
  const client = useMemo(() => {
    const authManager = new SukiAuthManager({
      partnerId: "YOUR_PARTNER_ID", // replace with your partner ID - required
      partnerToken: "YOUR_PARTNER_TOKEN", // replace with your partner token - required
      environment: "staging", // optional - default is "production"
      loginOnInitialize: true, // optional - default is false
      providerName: "John doe", // optional - default is empty
      providerOrgId: "1234", // optional - default is empty
      providerId: "1234567890", // optional - default is empty
      providerSpecialty: "FAMILY_MEDICINE", // optional - default is empty
    });
    return new DictationClient({ authManager }); // Step 4: Create the client
  }, []); // Step 5: Create the client once and reuse it across fields

  const [notes, setNotes] = useState("");
  const [dictationActive, setDictationActive] = useState(false);

  return (
    <DictationProvider client={client}>
      <textarea
        id="clinical-notes"
        value={notes}
        onChange={(e) => setNotes(e.target.value)}
      />
      <button
        type="button"
        onClick={() => setDictationActive((v) => !v)}
      >
        {dictationActive ? "Stop dictation UI" : "Start dictation"}
      </button>
      {dictationActive && (
        <Dictation
          fieldId="clinical-notes"
          mode="in-field" // required - you must set this as per your use case
          initialText={notes} // optional - you can set this to the initial text of the textarea
          onSubmit={({ text }) => setNotes(text)}
          onCancel={() => setDictationActive(false)}
        />
      )}
    </DictationProvider>
  );
}

Your integration is working when turning dictation on shows the hosted UI, committed text updates notes through onSubmit, and only one <Dictation> is mounted at a time for that shared client.

To wire rootElement with a ref (instead of document.getElementById), refer to Configuration examples and React integration guides for more details.

Next steps

Refer to the Configuration guide for more details on the available options and how to use them.

Get Started

Integration Guides

Feature Guides

Resources

Dictation SDK Quickstart

Prerequisites

Recommended integration pattern

Suki Auth Manager

Dictation Client

Dictation Provider (React only)

Dictation Per Active Field

Field IDs

Install the packages

Create your first dictation session

Next steps

​Prerequisites

​Recommended integration pattern

Suki Auth Manager

Dictation Client

Dictation Provider (React only)

Dictation Per Active Field

​Field IDs

​Install the packages

​Create your first dictation session

​Next steps

Prerequisites

Recommended integration pattern

Field IDs

Install the packages

Create your first dictation session

Next steps