Callbacks

Quick summary

The Suki Dictation SDK supports three callbacks: onSubmit, onCancel, and onDraft. These callbacks are called when the user commits, cancels, or drafts the dictation respectively. You can use these callbacks to handle the dictation result, cancel the session, or receive intermediate updates while the user is dictating.

Last updated:June 2026

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 surface. Refer to In-field mode and Scratchpad mode guides for behavior and layout.

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.

Next steps

Refer to Dictation modes and Scratchpad mode guides to learn more about the different modes and how to use them.

Get Started

Integration Guides

Feature Guides

Resources

Supported callbacks

Callback contract payload shape

Code examples

Next steps

​Supported callbacks

​Callback contract payload shape

​Code examples

​Next steps

Supported callbacks

Callback contract payload shape

Code examples

Next steps