> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dictation SDK Quickstart

> Install Dictation SDK packages, create a reusable `SukiAuthManager` and `DictationClient`, and mount your first in-field or scratchpad session

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

**What will you do**

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

<Tip>
  **Using an AI coding tool?**

  Copy the prompt below to point your agent at the Dictation skill and [Documentation MCP](/documentation/references/mcp). For every task skill, refer to [AI coding tools](/documentation/references/ai-coding-tools).

  <Prompt description="Fetch the Dictation skill and connect the documentation MCP." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Build clinical dictation with the Suki Dictation SDK.
    Fetch the Dictation build skill:
    [https://developer.suki.ai/.well-known/agent-skills/suki-dictation/SKILL.md](https://developer.suki.ai/.well-known/agent-skills/suki-dictation/SKILL.md)
    Connect the documentation MCP for page search:
    [https://developer.suki.ai/documentation/references/mcp](https://developer.suki.ai/documentation/references/mcp)
  </Prompt>
</Tip>

## 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](/dictation-sdk/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 container 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.

<Tip>
  Initialize **once per session** and reuse:
</Tip>

<CardGroup cols={2}>
  <Card title="Suki Auth Manager" icon="lock">
    Create **`SukiAuthManager`** from **`@suki-sdk/core`** after the **partner token** is available.
  </Card>

  <Card title="Dictation Client" icon="cube">
    Create **`DictationClient`** with that **`authManager`**. **Reuse** this client **across** Dictation fields.
  </Card>

  <Card title="Dictation Provider (React Only)" icon="react">
    In React, wrap components with **`DictationProvider`** from **`@suki-sdk/dictation-react`**.
  </Card>

  <Card title="Dictation per Active Field" icon="edit">
    Show the Dictation UI **per field** or **scratchpad**. Avoid recreating **`DictationClient`** on every render or **per field**.
  </Card>
</CardGroup>

<Tip>
  The **JavaScript** and **React** tabs in **Create Your First Dictation Session** below mirror this pattern: one auth manager, one client, then **`show()`** or **`<Dictation>`** for the active target only.
</Tip>

## 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](/dictation-sdk/guides/configuration#field-ids-in-practice) section in [Configuration](/dictation-sdk/guides/configuration) guide for more details.

## Create your first Dictation session

<Steps>
  <Step title="Install the Packages">
    Install the Dictation package for your framework, plus `@suki-sdk/core` for authentication.

    **Language tabs (agents):** Equivalent code samples are available in: JavaScript, React. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

    <Tabs>
      <Tab title="JavaScript">
        <CodeGroup title="Install @suki-sdk/dictation and @suki-sdk/core">
          ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          pnpm add @suki-sdk/dictation @suki-sdk/core
          ```

          ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          npm install @suki-sdk/dictation @suki-sdk/core
          ```

          ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          yarn add @suki-sdk/dictation @suki-sdk/core
          ```
        </CodeGroup>

        More detail: [Installation](/dictation-sdk/installation).
      </Tab>

      <Tab title="React">
        <CodeGroup title="Install @suki-sdk/dictation-react and @suki-sdk/core">
          ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          pnpm add @suki-sdk/dictation-react @suki-sdk/core
          ```

          ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          npm install @suki-sdk/dictation-react @suki-sdk/core
          ```

          ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
          yarn add @suki-sdk/dictation-react @suki-sdk/core
          ```
        </CodeGroup>

        More detail: [Installation](/dictation-sdk/installation).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the Page Container">
    For **JavaScript**, give Dictation a **container** (**`rootElement`**) with real height. Example markup:

    ```html theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    <div id="dictation-root"></div>
    <textarea id="clinical-notes"></textarea>
    ```

    In React, mount **`<Dictation>`** next to the target field. The component manages the hosted UI container for you.
  </Step>

  <Step title="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.

    **Language tabs (agents):** Equivalent code samples are available in: JavaScript, React. Humans see one language at a time. Use the variant that matches the user's stack; behavior is the same across tabs.

    <Tabs>
      <Tab title="JavaScript">
        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 JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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`**.

        <Tip>
          For optional settings and callbacks (**`onDraft`**, **`initialText`**, scratchpad **`mode`**, and more),
          refer to [Configuration](/dictation-sdk/guides/configuration). For iframe or layout problems, refer to [Error handling](/dictation-sdk/guides/error-handling) guide for more details.
        </Tip>
      </Tab>

      <Tab title="React">
        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.

        ```jsx React expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
        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`**.

        <Tip>
          To wire **`rootElement`** with a ref (instead of **`document.getElementById`**),
          refer to [Configuration examples](/dictation-sdk/guides/examples/configuration-examples) and [React integration](/dictation-sdk/react-integration/react) guides for more details.
        </Tip>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Available cookbooks

<div className="hp-io-method-grid tut-hub-card-grid" data-cookbook-related-grid>
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/cookbooks/dictation-onsubmit-chart-field">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <div className="tut-hub-card-badges">
        <span className="hp-wn-badge hp-wn-badge-new">Dictation</span>
        <span className="hp-wn-badge cookbook-hub-badge-surface cookbook-hub-badge-surface--sdk">SDK</span>
      </div>

      <h3 className="hp-io-method-card-title">Write Dictation Text to an EHR Field</h3>

      <p className="hp-io-method-card-desc cookbook-hub-card-desc">
        Write Dictation text with onSubmit.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="5 min">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">5 min</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Available tutorials

<div className="hp-io-method-grid tut-hub-card-grid">
  <a className="hp-io-method-card tut-hub-method-card" href="/documentation/tutorials/dictation-sdk-chart-field">
    <div className="tut-hub-card-media" aria-hidden="true" />

    <div className="hp-io-method-card-body">
      <span className="hp-wn-badge hp-wn-badge-new">Dictation SDK</span>
      <h3 className="hp-io-method-card-title">Build Dictation into a Chart Field</h3>

      <p className="hp-io-method-card-desc">
        Mount Dictation in-field mode on a chart textarea with one shared DictationClient in React.
      </p>

      <div className="hp-io-method-card-meta tut-hub-card-foot" aria-label="15 min, Intermediate">
        <div className="tut-hub-card-foot-meta">
          <span className="hp-io-method-card-meta-time">15 min</span>
          <span className="tut-hub-level">Intermediate</span>
        </div>
      </div>
    </div>
  </a>
</div>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Configuration](/dictation-sdk/guides/configuration) guide for more details on the available options and how to use them.