Skip to main content
Quick summary
Configuration has two parts. First, AuthConfig: the object you pass to new SukiAuthManager({ ... }) from @suki-sdk/core. That step covers sign-in, tokens, and optional provider registration before dictation can run.

Second, ShowOptions: what you pass to DictationClient.show() or as props on Dictation in React. That step sets mode and field, anchors the iframe in your layout, seeds text, and registers callbacks for each dictation session.
Last updated:April 2026

​
Overview

Dictation configuration has two steps: authenticate with Suki for Partners, then define how each dictation session is shown in your app.
1

Authenticate with the Suki for Partners

Build an AuthConfig object and pass it to new SukiAuthManager({ ... }) from @suki-sdk/core. The manager handles your connection to the platform. Configure:
  • Partner ID and partner token: Credentials Suki issues for your integration.
  • Provider: Optional fields that identify the clinician (for example providerId, providerName).
  • Environment: Target SDP environment ("staging" or "production").
  • Login behavior: Whether the manager signs in when it is created (loginOnInitialize) or you call login() later.
SukiAuthManager signs in and refreshes tokens from these settings. Authentication must succeed before the hosted dictation iframe can open.
2

Define session options

Pass a ShowOptions object whenever you start a session. In JavaScript, pass it to DictationClient.show(). In React, pass the same fields as props on Dictation.Typical ShowOptions fields include:
  • Mode: How the dictation UI is presented (for example in-field vs scratchpad).
  • Field: Stable field identifiers the SDK uses for callbacks.
  • Mounting: Where the iframe attaches in your DOM (rootElement).
  • Seed text: Optional starting text for the session.
  • Callbacks: Handlers for submit, cancel, and draft events.
Modes control where the iframe lives. Read In-field mode and Scratchpad mode for UX and layout. For when each callback runs, see Callbacks.

​
AuthConfig

AuthConfig is the object you pass to new SukiAuthManager({ ... }). It is used to configure the Suki Auth Manager. SukiAuthManager runs first in the lifecycle: it validates this configuration, signs in to SDP with your partner credentials, and refreshes tokens so the hosted dictation iframe can open. Until auth succeeds, dictation does not start.

​
AuthConfig properties

If autoRegister is enabled, provider metadata may be required in addition to the fields above.

​
ShowOptions

ShowOptions is what you pass to await dictationClient.show({ ... }). It is used to configure the Suki Dictation Client using the JavaScript package. In React, Dictation accepts the same fields as props wherever the shipped types expose them (mode, fieldId, rootElement, initialText, onSubmit, onCancel, onDraft, and so on). Think of it as one contract: imperative object vs declarative props.

​
ShowOptions properties

If onSubmit is missing, dictation often closes immediately after the user acts. Treat it as required in real integrations.

​
Field IDs in practice

fieldId is a stable string you choose to identify which note field or dictation target this session is for. The SDK includes it on every callback together with text, so you can match each transcript to the correct field in your app. You can use any stable string. A common shortcut is to use the same value as the target control’s HTML id: then in onSubmit you can run document.getElementById(fieldId) and assign text to that element. If you prefer another naming scheme, fieldId does not have to match a DOM id; just route text in your handler using the fieldId you chose. For structured notes, common examples are soap.subjective, soap.objective, soap.assessment, and soap.plan. For a scratchpad or floating session, a dedicated id such as scratchpad (or a namespaced value if you run more than one) keeps callbacks unambiguous.
  • Each active dictation instance should have its own stable id. If you call show() again, you replace the active session; you do not need hide() between fields for that pattern.
  • The object every callback receives is documented in Callback contract payload shape in the Callbacks guide.

​
Callback argument shape

For the callback argument payload shape, refer to Callback argument shape.

​
Wrapper layout

A wrapper layout is the layout where rootElement is a dedicated container (usually a div) with stable width and height, not the raw <textarea> or <input> you dictate into. Note fields grow and reflow with content; the iframe needs a host whose dimensions you control. Set rootElement to that container. The SDK inserts the dictation UI there and sizes it to that element’s width and height. When that element is too small, has no height, or resizes often (for example when a flex or grid parent collapses), the UI may show a blank area, look clipped, or jump when the page reflows. To create a wrapper layout, follow these best practices:
  • Add that div where the iframe should live, often beside or over the note field.
  • Give it a real height (height, min-height, or a parent that already has height) so the iframe has room to draw.
  • Use position: relative on the wrapper when you need the overlay to align with the rest of your layout.
CSS
/* Class on the element you pass as rootElement, or on an outer host that sizes the region */
.wrapper {
  position: relative;
  height: 100%;
}
If problems persist, check parent overflow, flex or grid shrink rules, container position, and CSP rules that block the iframe.

​
Best practices

For callbacks, you should always implement the onSubmit callback. If you do not, dictation will often close immediately after the user acts.
onSubmit: ({ fieldId, text }) => {
  // Your code to handle the submitted text
}
For layout, you should use a dedicated wrapper container instead of attaching directly to inputs.
<div class="wrapper">
  <textarea id="clinical-notes"></textarea>
</div>

.wrapper {
  position: relative;
  height: 100%;
}
For mode usage, you should use the in-field mode when dictation is tied to a specific text field or editor, and the scratchpad mode when dictation is not tied to a specific text field or editor.
mode: "in-field",

mode: "scratchpad",

​
Next steps

Refer to the Error handling guide for more details on common issues and how to troubleshoot them.
Last modified on April 20, 2026