Skip to main content
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.
Using an AI coding tool?Copy the prompt below to point your agent at the Dictation skill and Documentation MCP. For every task skill, refer to AI coding tools.

Fetch the Dictation skill and connect the documentation MCP.

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. 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 in Create 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.

Steps

1

Install the Packages

Install the Dictation package for your framework, plus @suki-sdk/core for authentication.
More detail: Installation.
2

Add the Page Container

For JavaScript, give Dictation a container (rootElement) with real height. Example markup:
In React, mount <Dictation> next to the target field. The component manages the hosted UI container for you.
3

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

Next steps

Refer to the Configuration guide for more details on the available options and how to use them.
Last modified on August 7, 2026