Suki Dictation SDK
Embed real-time clinical dictation into browser applications using the Suki Dictation SDK.
Supports:
- In-field dictation overlays
- Scratchpad dictation surfaces
- Framework-agnostic JavaScript usage
- First-class React integration
- Secure SDP authentication lifecycle
Quickstart
Install
npm install @suki-sdk/dictation @suki-sdk/core
Initialize
import { SukiAuthManager } from "@suki-sdk/core"
import { DictationClient } from "@suki-sdk/dictation"
const authManager = new SukiAuthManager({
partnerId: "YOUR_PARTNER_ID",
partnerToken: "YOUR_PARTNER_TOKEN",
environment: "staging",
loginOnInitialize: true
})
const client = new DictationClient({ authManager })
await client.show({
mode: "in-field",
fieldId: "notes",
rootElement: document.getElementById("dictation-root"),
onSubmit: ({ text }) => console.log(text)
})
Tip: This is the minimal working integration. Most applications only need to customize callbacks and container placement.
Choosing the Right Package
| Scenario | Package |
|---|
| Dictation only (JavaScript) | @suki-sdk/dictation |
| Dictation only (React) | @suki-sdk/dictation-react |
Architecture Overview
The SDK embeds dictation using a sandboxed iframe controlled by a lightweight lifecycle client.
Your App
↓
DictationClient
↓
IframeMessenger
↓
Dictation iframe (Suki hosted)
| Layer | Responsibility |
|---|
| Application | Decides when and where dictation appears |
| DictationClient | Manages session lifecycle |
| SukiAuthManager | Handles authentication + token refresh |
| Iframe | Speech UI + transcription engine |
Note: The iframe is isolated from host CSS and DOM to ensure consistent rendering across integrations.
Installation
JavaScript apps:
npm install @suki-sdk/dictation @suki-sdk/core
npm install @suki-sdk/dictation-react @suki-sdk/core
Authentication
All integrations begin with SukiAuthManager.
new SukiAuthManager({
partnerId,
partnerToken,
environment: "staging",
loginOnInitialize: true
})
- Validates configuration
- Authenticates with SDP
- Refreshes tokens automatically
- Provides iframe credentials
Warning: Invalid credentials will prevent iframe initialization.
Initialization Lifecycle
Create AuthManager
↓
(optional) login()
↓
Create DictationClient
↓
show()
↓
Session active
↓
hide()
React integrations automatically manage show() and hide().
JavaScript Integration
Use the imperative API when integrating with:
- Vanilla JS apps
- Non-React frameworks
- Multiple dynamic editors
- Custom overlay systems
await dictationClient.show({
mode: "in-field",
fieldId: "assessment",
rootElement,
initialText,
onSubmit,
onCancel
})
React Integration
Wrap once:
<DictationProvider client={client}>
{activeField === "notes" && (
<Dictation
fieldId="notes"
mode="in-field"
initialText={value}
onSubmit={handleSubmit}
/>
)}
hide().
Tip: Use state like activeFieldId to control which input owns the dictation session.
Dictation Modes
Two interaction modes are supported:
| Mode | Behavior |
|---|
in-field | Overlays input container |
scratchpad | Floating standalone dictation UI |
scratchpad when dictation is not tied to a specific input field.
Switching Between Fields
Calling show() again automatically replaces the active session.
show(fieldA)
show(fieldB)
hide(fieldA)
show(fieldB)
Callback Contract
All callbacks receive:
{
fieldId: string,
text: string
}
| Callback | Required | Purpose |
|---|
onSubmit | Yes | Commit dictation result |
onCancel | Optional | Discard session |
onDraft | Optional | Unstaged text when user does not submit and switches context; partner persists only if they handle it |
onSubmit: ({ fieldId, text }) => save(fieldId, text)
Configuration Reference
AuthConfig
| Field | Required | Description |
|---|
partnerId | Yes | Partner identifier |
partnerToken | Yes | Partner auth token |
environment | Optional | "staging" or "production" |
autoRegister | Optional | Enable provider auto-registration |
loginOnInitialize | Optional | Login during construction |
Provider metadata may be required when auto-registration is enabled.
ShowOptions
| Field | Required | Description |
|---|
mode | Yes | "in-field" or "scratchpad" |
fieldId | Yes | Identifier echoed in callbacks |
rootElement | Recommended | Container element for iframe |
initialText | Optional | Seed content |
onSubmit | Yes | Completion callback |
onCancel | Optional | Cancellation callback |
onDraft | Optional | Unstaged text when the user does not submit and moves on (for example, another field); not per-keystroke streaming |
Runtime Requirements
Supported environments:
- ✅ Browser
- ❌ Node.js
- ❌ SSR iframe rendering
The SDK depends on:
HTMLIFrameElementpostMessage- DOM layout sizing
Best Practices
Use a wrapper container instead of attaching directly to inputs:
textarea-wrapper
└── iframe overlay
.wrapper {
position: relative;
height: 100%;
}
Error Handling
Most integration errors originate from:
| Source | Cause |
|---|
AuthManager | Invalid credentials |
| iframe | Blocked domain / CSP |
| Configuration | Missing callbacks |
| Layout | Container has zero height |
try {
await client.show(...)
} catch (err) {
console.error(err)
}
Troubleshooting
Dictation UI not visible
Check:
- Container height
- CSP iframe restrictions
- Missing
rootElement
- Authentication failure
Usually indicates a missing onSubmit callback.
Multiple overlays appearing
Ensure only one DictationClient instance exists per page scope.Last modified on April 20, 2026
