Callbacks

Wire onSubmit, onCancel, and onDraft callbacks in JavaScript or React, including payload shape, fieldId routing, and when each handler fires

Callbacks allow your application to run your own code when the user commits, cancels, or moves on without committing during Dictation. You supply functions; the Suki Dictation SDK calls them when those events occur. You do not poll on a timer or in a loop for new text.

Registering callbacks

When you start a session, register them in JavaScript as properties on the object you pass to DictationClient.show(), or in React as props on <Dictation>.

Callback execution

It calls onSubmit after the user commits, and onCancel if they leave without committing. If you supply onDraft, the SDK may call it when the user does not submit and switches to another field (or otherwise moves on without committing). onDraft is not invoked on every live transcript change while Dictation stays on one field. The SDK does not persist draft text to your systems; only your onDraft handler decides whether to store or send it to your partner backend.

Payload

Every callback receives the same argument: one object, { fieldId, text }. The fieldId value is whatever you passed into show() or <Dictation>. A common pattern is to set it to the same value as the target control’s id, so onSubmit can use document.getElementById(fieldId) and write text into that element.

Supported callbacks

Dictation SDK supports the following callbacks:

Hide Supported callbacks

onSubmit · function · required

Runs when the user commits the Dictation result.

onCancel · function

Optional: Runs when the user discards the session without committing.

onDraft · function

Optional. May run when the user leaves Dictation without submitting and switches context (for example, to another field). Use it if you want to capture unstaged transcript text; the SDK does not save or forward it unless you do.

Mode controls how Dictation is shown. Set it to in-field when the UI is tied to a container on your page, or scratchpad for a standalone Dictation UI. Refer to In-field mode and Scratchpad mode guides for behavior and layout.

Content Rewrite runs inside the hosted iframe and does not add callbacks. When the clinician submits, onSubmit still receives { fieldId, text } for the full field, including rewritten text. Refer to Content Rewrite for more details.

For every other option you pass to DictationClient.show() or to <Dictation> as props, including rootElement, initialText, and these callbacks, use the Configuration reference.

Callback contract payload shape

All callbacks receive a single argument: an object with these fields:

Hide Callback contract payload shape

fieldId · string · required

This is the string you invent to name this Dictation session. The SDK includes it in every callback so you know which field the text is for. Using the same text as your input’s id (for example clinical-notes) is a simple way to tie them together.

text · string · required

The transcript string for this callback (committed result, state at cancel, or interim draft, depending on which handler ran).

Example:

JavaScript

// After the user commits, your onSubmit might receive:
{
  fieldId: "clinical-notes",
  text: "The user said hello.",
}

For structured notes, use stable, unique ids per section, for example soap.subjective, soap.objective, soap.assessment, soap.plan, or scratchpad for a floating session. See Field IDs.

If onSubmit is missing, Dictation often closes immediately after the user acts. Always implement onSubmit.

Code examples

Use callbacks as properties on the object you pass to await dictationClient.show({ ... }). They sit alongside mode, fieldId, rootElement, initialText, and other options from Configuration.

The iframe resizes to the container you pass as rootElement when you use in-field mode.

JavaScript

import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/dictation";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID", // Required
  partnerToken: "YOUR_PARTNER_TOKEN", // Required
  environment: "staging", // Optional
  loginOnInitialize: true,
  autoRegister: false, // Optional - default is false
  providerId: "YOUR_PROVIDER_ID", // Optional - required if autoRegister is true
  providerName: "YOUR_PROVIDER_NAME", // Optional - required if autoRegister is true
  providerOrgId: "YOUR_PROVIDER_ORG_ID", // Optional - required if autoRegister is true
  providerSpecialty: "YOUR_PROVIDER_SPECIALTY", // Optional - required if autoRegister is true
});

const dictationClient = new DictationClient({ authManager });

// Example markup for in-field:
// <div id="clinical-notes-dictation-root"></div>
// <textarea id="clinical-notes"></textarea>

await dictationClient.show({
  mode: "in-field",
  fieldId: "clinical-notes", // same string as id="clinical-notes" on your textarea
  rootElement: document.getElementById("clinical-notes-dictation-root"),
  initialText: document.getElementById("clinical-notes")?.value ?? "",
  onSubmit: ({ fieldId, text }) => {
    const el = document.getElementById(fieldId);
    if (el) el.value = text;
  },
  onCancel: ({ fieldId, text }) => {
    // Optional: user cancelled without committing
  },
  onDraft: ({ fieldId, text }) => {
    // Optional: e.g. user switched fields without submit; persist draft in your app if needed
  },
});

Calling show() again replaces the active session; you do not need to call hide() between fields for that pattern. Wrap show() in try / catch if you want to log configuration or auth failures.

Refer to the Error handling guide for more details.

For more on imperative show() and one client per page scope, refer to the JavaScript integration guide for more details.

Available cookbooks

Next steps

Dictation modes

Scratchpad mode