> ## 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.

# Audio Dictation

> Learn how Audio Dictation turns spoken speech into real-time text. Align on workflow decisions, choose Dictation APIs, Web SDK, or Dictation SDK, then design where transcript text lands in your app

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    Audio Dictation converts spoken speech into text in real time. Instead of typing into fields or note sections, providers can speak naturally while your application receives intermediate and final transcripts to insert, review, and save.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">August 2026</span>
  </div>
</div>

Audio Dictation lets you convert provider speech into transcribed text while a Dictation session is active. Providers and patients speak and your application receives intermediate and final transcripts in real time. You insert that text into a field, note section, or stream it your downstream workflow, then let the provider review and save.

Audio Dictation is speech-to-text and is different from ambient note generation workflows.

<span id="ambient-vs-audio-dictation" />

### When to use Ambient documentation vs Audio Dictation

Ambient documentation and Audio Dictation solve different problems.

* Use **Ambient documentation** when you want Suki to listen to a clinical conversation and help generate documentation from the encounter. Refer to [Ambient clinical documentation](/documentation/concepts/ambient-clinical-notes/ambient-documentation).
* Use **Audio Dictation** when the provider needs direct control over the exact content, wording, structure, and pace of documentation.

In most scenarios, organizations need both. Design your UX so providers know when to start ambient sessions, when to switch into Dictation, and when to use Dictation to correct ambient-generated content.

When you use Audio Dictation, it helps clinicians to:

* Speak naturally and receive transcribed text in real time.
* Insert text into fields, note sections, or a scratchpad without manual typing.
* Correct transcript text while clinical context is still fresh.
* Save or submit documentation after review.

**What you build for Audio Dictation to work**

* You need to choose where dictated text should land in your application.
* Capture provider speech with Dictation APIs, Web SDK, or Dictation SDK modalities.
* Receive intermediate and final transcript text.
* Insert text into the active target in your application, then let the provider review and save the transcript text.

## Choose your path to build Audio Dictation

Suki provides three integration options for Audio Dictation workflows. Pick the one that matches how much UI and streaming control you want Suki to own, and how much you want to own, then open the matching quickstart to get started.

<CardGroup cols={2}>
  <Card title="Dictation APIs" icon="code">
    **If you need:** full control over sessions, WebSocket audio, and transcript handling in your own UI.

    Your application owns create session, stream audio, render transcripts, and save text.

    <div style={{marginTop: '1rem'}}>
      <a href="/documentation/how-to/dictation/dictation-basic-usage" className="learning-path-button">Dictation Basic Usage</a>
    </div>
  </Card>

  <Card title="Web SDK" icon="browser">
    **If you need:** browser-based Dictation inside your own page layout and fields.

    Suki provides Dictation components and shared auth. Your application owns field focus and where final text goes.

    <div style={{marginTop: '1rem'}}>
      <a href="/web-sdk/dictation-overview" className="learning-path-button">Web SDK Dictation</a>
    </div>
  </Card>

  <Card title="Dictation SDK" icon="window">
    **If you need:** hosted iframe-based Dictation with in-field or scratchpad modes.

    Suki manages the hosted Dictation experience. Your application handles callbacks that insert text into your UI.

    <div style={{marginTop: '1rem'}}>
      <a href="/dictation-sdk/quickstart" className="learning-path-button">Dictation SDK Quickstart</a>
    </div>
  </Card>
</CardGroup>

Use this table if you are still deciding which modality to use:

| Scenario                                                                                 | Best fit       |
| ---------------------------------------------------------------------------------------- | -------------- |
| You create sessions, stream on `/ws/transcribe`, and handle transcripts in your own code | Dictation APIs |
| Your backend or non-browser client owns audio capture                                    | Dictation APIs |
| Browser app in JavaScript or React with your own page layout and fields                  | Web SDK        |
| Dictation into a specific input with a Suki-hosted iframe                                | Dictation SDK  |
| Dictation in a scratchpad panel, not tied to one field                                   | Dictation SDK  |

<Tip>
  Do not have credentials yet? Complete the following steps:

  * Complete [Partner onboarding](/documentation/get-started/partner-onboarding).
  * Then [Partner authentication](/documentation/how-to/partner-authentication) to get an `sdp_suki_token`.
  * Staging base URL for API examples: `https://sdp.suki-stage.com` or ask your Suki representative for the staging base URL.
</Tip>

### Verify your first Dictation workflow

Before you design the full production workflow for Audio Dictation, confirm that your staging integration can complete the Dictation path for the product you chose:

* Authenticate successfully for your chosen product.
* Start Dictation against a real target in your UI, such as a field, note section, or scratchpad.
* Capture provider speech.
* Receive transcript text in your UI or SDK callbacks.
* Insert or display that text in the active target.
* Let the provider correct the text, then save it in your application.

After you have verified that your Dictation path works end to end on staging, continue with field targeting, mode choice, and rollout measurement for production.

## How Audio Dictation works

Across products, the clinician workflow for Audio Dictation is the same. The only difference is who owns each step. Refer to the table below to see who owns each step for each modality.

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
flowchart LR
    A[Provider chooses field<br/>or note section] --> B[Start dictation]
    B --> C[Capture speech]
    C --> D[Receive transcript<br/>text]
    D --> E[Insert text into<br/>active target]
    E --> F[Provider reviews<br/>and corrects]
    F --> G[Save documentation]

    style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style G fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
```

| Step                | Dictation SDK                   | Web SDK                        | Dictation APIs                           |
| ------------------- | ------------------------------- | ------------------------------ | ---------------------------------------- |
| Start Dictation     | Hosted iframe / SDK controls    | SDK Dictation components       | Your app creates the session             |
| Capture audio       | Hosted experience               | Browser capture in SDK         | Your app streams over WebSocket          |
| Get transcript text | Callbacks                       | Component events and callbacks | Your app handles transcript frames       |
| Place text in UI    | Your app inserts from callbacks | Your app owns field targets    | Your app owns rendering and insert logic |

If you are building with Partner APIs, follow [Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage) for how to create a session, stream audio, receive transcripts, and end the session.

## Decide before you build your workflow

Before you pick Dictation APIs, Web SDK, or Dictation SDK for production, align on a few product decisions. Agree where dictated text lands, which Dictation mode you need, how providers move between fields, and how Ambient and Dictation work together if you offer both. These choices shape UX, integration timeline, and which Suki products you combine for a best-fit solution.

Use the following sections to align your team.

**Accordions (agents):** product decisions before you pick Dictation APIs, Web SDK, or Dictation SDK. Humans expand one accordion at a time. Read all of them for the full decision set.

* **Define where dictated text lands:** Choose the UI target (field, note section, editor, or scratchpad). Dictation is speech-to-text only. It does not generate an Ambient note or Form filling structured fields.
* **Decide if you also need Ambient:** Ambient generates the visit note. Dictation adds exact wording later. If you offer both, use separate **Record visit** and **Speak** controls. Do not share one mic or run both at once. Sequence: Ambient create → context → stream → end → poll → content, then Dictation create → `/ws/transcribe` → insert into the field your UI selected. Dictation does not take a LOINC target. Ambient personalization does not change Dictation transcripts. WebSocket contracts differ (`data` / `RU9G` vs `audioData` / `AUDIO_END`).
* **Choose in-field, scratchpad, or API-owned UI:** Dictation SDK and Web SDK support in-field and scratchpad. Dictation APIs mean your app owns streaming and insert.
* **Plan how text is committed and saved:** SDK paths use `onSubmit` / `onDraft` and `fieldId`. API paths own frames and EHR save. Dictation has no partner completion webhook like Ambient.
* **Plan review and correction:** Decide live vs post-dictate correction, field switching, and when documentation is final. Keep voice commands out of clinical text.

<AccordionGroup>
  <Accordion title="Define Where Dictated Text Lands" icon="input-text">
    Be clear about **where** transcript text goes in your application. Common targets includes

    * free-text note editor.
    * single chart field.
    * note section.
    * scratchpad panel.

    Dictation returns speech-to-text. It does not generate an Ambient clinical note or Form filling structured fields.

    Start with one target workflow, for example one high-use chart field or one note section. A focused first path is easier to pilot and measure.
  </Accordion>

  <Accordion title="Decide If You Also Need Ambient" icon="waveform">
    Ambient and Dictation solve different problems. Ambient listens to the visit and generates a structured clinical note after the session ends. Dictation gives the provider real-time control over exact wording in a field or note area.

    Many organizations need both. Decide early whether your app supports Dictation only, or Ambient plus Dictation.

    Make the choice obvious in the UI. Providers should know when to run an ambient session for the visit and when to dictate into a field, including when Dictation is used to correct ambient-generated text.

    ### Build a visit chart with Ambient and Dictation

    If your visit chart supports both **Ambient** and **Dictation**, expose them as separate controls with separate workflows.

    Use **Record visit** for Ambient to capture the visit and generate the clinical note. Use **Speak** for Dictation when the clinician needs to enter exact wording into a specific section or field.

    Do not use a single microphone control for both workflows, and do not run Ambient and Dictation at the same time.

    ### Recommended workflow

    The typical workflow is:

    ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
    flowchart LR
        A[Record visit] --> B[Generate note]
        B --> C[Review note]
        C --> D[Speak into a<br/>specific section]

        style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    ```

    1. The clinician starts **Record visit** to capture the visit with Ambient.
    2. Your application waits for the ambient session to reach **`completed`**.
    3. Your application displays the generated note for review.
    4. The clinician selects a note section or chart field where they want to add exact wording.
    5. The clinician taps **Speak** to start Dictation.
    6. Your application inserts the final Dictation transcript into the selected field.

    ### Build the UI around these states

    | UI state                          | Record visit      | Speak                                         | What happens                                                                                                                                      |
    | :-------------------------------- | :---------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Before the visit / chart open** | Enabled           | Optional                                      | The clinician can start an ambient session. If your product supports Dictation for other chart fields, Speak can also be available.               |
    | **Ambient recording**             | Active            | **Disabled**                                  | Ambient has exclusive access to the microphone. Do not start Dictation or open `/ws/transcribe` while Ambient is streaming.                       |
    | **Generating the note**           | Disabled          | **Disabled**                                  | Wait for the ambient session to reach a terminal status. Keep Speak disabled until the note is ready.                                             |
    | **Note ready (`completed`)**      | Enabled if needed | **Enabled** for the selected section or field | Display the generated note. When the clinician selects a section and taps Speak, start Dictation and insert the final transcript into that field. |
    | **Ambient `skipped` or `failed`** | Enabled for retry | Off or limited                                | Let the clinician retry Ambient. Do not treat an empty or missing Ambient note as a Dictation problem.                                            |

    ### API flow

    Your application should follow this sequence:

    <Steps>
      <Step title="Start and Complete Ambient" icon="waveform">
        1. Create the ambient session.
        2. Provide the visit context, including sections and any other context your integration supports.
        3. Stream the visit audio.
        4. End the ambient session.
        5. Poll the session status until processing reaches a terminal state.
        6. Retrieve the generated note content and any optional structured data.
      </Step>

      <Step title="Display the Generated Note" icon="file-lines">
        When the ambient session reaches **`completed`**, display the generated note so the clinician can review it.
      </Step>

      <Step title="Let the Clinician Select a Target Field" icon="bullseye">
        The clinician selects the note section or chart field where they want to add text.

        Your application owns this mapping. For example, your UI can associate the selected control with a LOINC code or your own field ID.
      </Step>

      <Step title="Start Dictation" icon="microphone">
        When the clinician taps **Speak**:

        1. Create the Dictation session.
        2. Open the Dictation `/ws/transcribe` WebSocket.
        3. Stream the clinician's speech.
        4. Receive the final transcript.
        5. Insert the transcript into the field selected in your UI.
        6. Save the updated content through your EHR workflow.
      </Step>
    </Steps>

    ### Section targeting is your responsibility

    Dictation does **not** accept a LOINC code or other section target.

    Your application determines where the Dictation transcript goes. Track the selected section or field in your UI and insert the final transcript into that location.

    For example:

    ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFF394','primaryTextColor':'#111827','primaryBorderColor':'#FFE148','lineColor':'#FFE148','secondaryColor':'#FFF394','tertiaryColor':'#FFFADE','mainBkg':'#FFF394','secondBkg':'#FFFADE','tertiaryBorderColor':'#FFE148','border1':'#FFE148','border2':'#FFE148','arrowheadColor':'#FFE148','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','nodeBorder':'#FFE148','edgeLabelBackground':'#FFE148','clusterBkg':'#FFFADE','clusterBorder':'#FFE148','defaultLinkColor':'#FFE148','titleColor':'#111827','nodeTextColor':'#111827'}}}%%
    flowchart TB
        A[Clinician selects Assessment] --> B[Your UI stores the<br/>selected field ID]
        B --> C[Clinician taps Speak]
        C --> D[Dictation captures speech]
        D --> E[Final transcript is returned]
        E --> F[Your UI inserts the transcript<br/>into Assessment]

        style A fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style B fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style C fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style D fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style E fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
        style F fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    ```

    Ambient and Dictation also have different personalization behavior.

    **Ambient personalization** affects the style and format of the generated Ambient note. It does **not** change Dictation transcripts.

    <Warning>
      Do not stream Ambient and Dictation from the same device microphone at the same time.

      Disable **Speak** while Ambient is recording, or stop or pause the Ambient workflow before starting Dictation. Ambient and Dictation use different WebSocket contracts: Ambient uses `data` / `RU9G`, while Dictation uses `audioData` / `AUDIO_END`.

      See [Ambient vs Dictation streaming](/documentation/how-to/audio-streaming/audio-stream) for details.
    </Warning>

    ### The integration pattern

    Treat Ambient and Dictation as **two sequential tools in the same visit**, not as two modes of the same microphone:

    * **Ambient** captures the visit and generates the clinical note.
    * **Dictation** adds exact clinician-specified text after the note is available.
    * **Your UI** decides which section or field receives the Dictation transcript.
    * **Only one workflow should use the device microphone at a time.**
  </Accordion>

  <Accordion title="Choose In-Field, Scratchpad, or API-Owned UI" icon="window">
    Mode choice depends on the product you use:

    * **In-field Dictation:** Hosted Dictation over a specific input. Supported by [Dictation SDK](/dictation-sdk/guides/in-field-mode) and Web SDK Dictation (`mode="in-field"`).
    * **Scratchpad Dictation:** Hosted Dictation in a panel that is not tied to one field. Supported by [Dictation SDK](/dictation-sdk/guides/scratchpad-mode) and Web SDK Dictation (`mode="scratchpad"`).
    * **API-owned UI:** Your application owns create session, `/ws/transcribe` streaming, transcript rendering, and insert logic. Use [Dictation APIs](/documentation/how-to/dictation/dictation-basic-usage).

    Pick the mode that matches how providers move through documentation. Do not force scratchpad UX when the workflow is one focused field.
  </Accordion>

  <Accordion title="Plan How Text Is Committed and Saved" icon="check">
    Decide when transcript text becomes part of the chart.

    For Dictation SDK and Web SDK Dictation, commit text through callbacks such as `onSubmit`, and optionally `onDraft` when the provider leaves without a final commit. Use a stable `fieldId` so your app knows which field to update. You can seed Dictation with `initialText` when the field already has content.

    For Dictation APIs, your application owns how partial and final transcript frames update the UI, and when the provider saves the final text in your EHR workflow.

    Partner webhooks for session completion are documented for Ambient and Form filling workflows. Dictation integrations rely on the live WebSocket transcript path and your application save logic.
  </Accordion>

  <Accordion title="Plan Review and Correction" icon="user-edit">
    Providers should be able to correct transcript text while the visit context is still fresh.

    Decide:

    * Whether correction happens in the field as text arrives, or after a longer dictate completes.
    * How providers switch fields without inserting navigation commands into clinical text.
    * When documentation is final in your application: save, sign, or submit.

    If your application supports voice commands, handle those commands in your app workflow. Keep commands separate from dictated clinical text so a navigation command does not become part of the note.
  </Accordion>
</AccordionGroup>

## Design the clinician workflow

After those decisions are clear, turn them into a Dictation workflow your team can build. Use this table to align on the answers.

| Question                               | Example answer                            | Why it matters                                                                                                                                                                       |
| :------------------------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where does dictated text land?         | One chart field, then expand              | Dictation is for exact wording you place in your UI. For structured medical forms, use [Form filling](/documentation/concepts/form-filling/form-filling).                            |
| In-field, scratchpad, or API-owned UI? | In-field for focused charting             | Mode choice drives Dictation SDK and Web SDK setup. API path means you own the full UI.                                                                                              |
| How do providers move between fields?  | Explicit field focus in your app          | Avoid treating navigation speech as clinical text.                                                                                                                                   |
| How should providers review output?    | Correct live in the field                 | Live correction works better than waiting until the end of a long dictate.                                                                                                           |
| When is documentation final?           | Save after provider review                | Make save, sign, and submit states explicit in your application.                                                                                                                     |
| Do you also offer Ambient?             | Yes: Record visit, then Speak per section | Separate entry points. Disable Speak while Ambient records or generates. See [Ambient clinical documentation](/documentation/concepts/ambient-clinical-notes/ambient-documentation). |
| Who owns the LOINC / field map?        | Your note template                        | Ambient returns `loinc_code`. Dictation inserts into whatever field your UI has focused.                                                                                             |

<Tip>
  Across Suki's products, the path stays the same: choose a target, start Dictation, capture speech, receive transcript text, insert it, then let the provider review and save.
</Tip>

## How to implement Audio Dictation

Next, align on the following implementation choices. These choices decide which Dictation product you use, how audio is captured, and how text reaches your UI.

### 1. Map the end-to-end Dictation workflow

Walk the documentation task from focused field to saved text. For each step, name who owns it: your app, Suki hosted UI, or your backend.

Typical stages:

1. Provider focuses a field, note section, or scratchpad target.
2. Start Dictation for that target.
3. Capture provider speech.
4. Receive intermediate and final transcript text.
5. Insert text into the active target.
6. Let the provider correct the text, then save it in your application.

If you also ship Ambient, map the handoff between ambient note review and Dictation correction so providers are not unsure which product to use.

### 2. Choose your audio capture strategy

Dictation quality depends on clear speech capture and a stable real-time transcript path. Pick the product that matches who should own the microphone UI and transcript handling.

| Capture path          | Best for                                                    | What you own                                                                       | Where to start                                                                 |
| :-------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| **Dictation SDK**     | Hosted iframe Dictation with in-field or scratchpad modes   | Field targeting, `fieldId`, callbacks (`onSubmit`, optional `onDraft`), save logic | [Dictation SDK quickstart](/dictation-sdk/quickstart)                          |
| **Web SDK Dictation** | Browser apps already on `@suki-sdk/js` or `@suki-sdk/react` | Field focus, mode (`in-field` or `scratchpad`), where final text goes              | [Web SDK Dictation](/web-sdk/dictation-overview)                               |
| **Dictation APIs**    | Custom UI or non-browser capture you control                | Create session, `/ws/transcribe` frames, transcript rendering, end session         | [Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage) |

For Dictation APIs, stream on **`GET /ws/transcribe`**. Send audio as documented for Dictation, use **`AUDIO_END`** when an utterance finishes, and handle partial and final frames with `is_final`. One Dictation session can support multiple speech bursts when the session returns to `READY` or `IDLE`. Refer to [Dictation audio streaming](/documentation/how-to/audio-streaming/dictation-streaming) and [Audio capture best practices](/documentation/how-to/audio-streaming/audio-capture-best-practices).

#### Best practices for clean audio implementation

Dictation APIs convert the provider's speech directly into text. They do not interpret or restructure speech into a clinical plan.

Because you control the UI and microphone handling when using Dictation APIs, the **quality of the audio** and the **way providers speak** can affect the transcript. For example, spoken language may include:

* **False starts:** A provider may repeat or restart part of a sentence, such as "Will I will" instead of "I will".
* **Filler words:** Words such as "um", "you know", or "basically" are transcribed when spoken.
* **Trailing phrases:** Casual phrases such as "okay" may appear at the end of an utterance.

You can add client-side processing to remove common fillers, handle false starts, and apply basic formatting such as **capitalization and punctuation**. This can make the transcript easier to read, but it does not add clinical structure or infer what the provider intended to say.

<Note>
  For the best results, encourage providers to speak in short, complete clinical sentences. For example, say **"Plan. Physical exam today. Ultrasound next week."** rather than **"I'll tell the patient basically, you know, maybe next week, okay."**
</Note>

### 3. Choose your Dictation mode and commit model

Decide how the provider starts Dictation and how text is committed.

| Approach         | What you configure                                             | Best for                                      |
| :--------------- | :------------------------------------------------------------- | :-------------------------------------------- |
| **In-field**     | Hosted Dictation bound to one input with a stable `fieldId`    | Chart fields and note sections                |
| **Scratchpad**   | Hosted Dictation panel, then your app places text where needed | Longer free-text draft before paste or insert |
| **API-owned UI** | Your rendering of partial and final transcript frames          | Fully custom Dictation UX                     |

For Dictation SDK and Web SDK, implement `onSubmit` so committed text reaches the right field. Use `onDraft` when you need text from an incomplete session. Seed with `initialText` when the field already has content. Refer to [Callbacks](/dictation-sdk/guides/callbacks) for Dictation SDK behavior.

### 4. Place text in your UI and save it

Dictation ends when your application has the transcript text the provider accepts. There is no Ambient-style clinical note retrieval step and no documented Dictation partner webhook completion flow.

**For Dictation SDK and Web SDK**

* Map `fieldId` to the correct input in your UI.
* Apply committed text from `onSubmit`.
* Save or submit through your existing EHR or chart workflow.

**For Dictation APIs**

* Update your UI from WebSocket transcript frames.
* Keep a cumulative transcript as frames arrive, including the complete transcript returned when you end the session when your integration uses that response.
* Persist the final text in your application after provider review.

Do not treat Dictation transcript text as ambient note content or Form filling `generated_values`. Keep each product’s output on its own save path.

## Common integration patterns and use cases

Design your Dictation integration around where transcribed text must land and whether you own the streaming pipeline yourself or use an SDK.

The following patterns show common ways to build Dictation workflows:

<CardGroup cols={2}>
  <Card title="In-Person Clinical Dictation" icon="user">
    Capture provider Dictation during in-person encounters and return transcribed text to your documentation workflow.
  </Card>

  <Card title="Virtual Visit Documentation Screens" icon="video">
    Capture provider Dictation in browser or API workflows used during virtual visits, then place transcript text into your documentation screens.
  </Card>

  <Card title="Populate Fields in Your Web App" icon="input-text">
    Stream Dictation into note fields, forms, or scratchpad areas using Web SDK or Dictation SDK patterns.
  </Card>

  <Card title="Custom Transcription Pipeline" icon="code">
    Own session lifecycle, audio capture, and transcript handling end to end with Partner REST and WebSocket APIs.
  </Card>
</CardGroup>

## Measure success for Audio Dictation

Treat measurement as something you own. Define what **better** and **worse** means for your Audio Dictation workflow, track it where the work happens (your app + EHR), and use the findings before and after you deploy Dictation in production.

| Metric type           | Examples you can track                                                   | What it tells you                                  |
| --------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- |
| **Time**              | Time to complete a note section, documentation time per encounter        | Whether Dictation reduces typing load              |
| **Quality and trust** | Edits after insert, re-dictate rate, accepted transcript segments        | Whether providers trust live transcript text       |
| **Rework**            | Discarded transcripts, sections rewritten from scratch                   | Whether dictated text needs too much cleanup       |
| **Reliability**       | Session failures, stream failures, empty transcripts                     | Whether the integration is stable in production    |
| **Adoption**          | Active Dictation users, sessions per provider, fields completed by voice | Whether clinicians use Dictation in real workflows |

Start with a small set of metrics, for example time to complete target fields, edit rate after insert, and session failure rate, and later add more metrics as you deploy Dictation in production.

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Dictation audio streaming](/documentation/how-to/audio-streaming/dictation-streaming)** - Stream Dictation audio on `/ws/transcribe`.

<Icon icon="file-lines" iconType="solid" /> **[Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage)** - Build Dictation with Partner APIs when you own the streaming pipeline.

<Icon icon="file-lines" iconType="solid" /> **[Web SDK Dictation](/web-sdk/dictation-overview)** - Add Dictation to browser JavaScript or React applications.

<Icon icon="file-lines" iconType="solid" /> **[Dictation SDK quickstart](/dictation-sdk/quickstart)** - Embed hosted in-field or scratchpad Dictation.

<Icon icon="file-lines" iconType="solid" /> **[Partner authentication](/documentation/how-to/partner-authentication)** - Get an `sdp_suki_token` for API and SDK calls.
