Content Rewrite

Content Rewrite lets clinicians rewrite selected text in the hosted Dictation iframe before they submit. It is available in the Dictation SDK (@suki-sdk/dictation and @suki-sdk/dictation-react) and in Web SDK Dictation, which uses DictationClient from @suki-sdk/js and @suki-sdk/react. It works in both In-field mode and Scratchpad mode. Content Rewrite runs entirely in the hosted iframe. You do not send a rewrite API call, handle selection offsets, or apply the rewritten span. When a clinician selects text with the microphone off, the iframe shows the rewrite tooltip, sends the request, and applies the result. Your existing onSubmit and onDraft callbacks receive the updated field text.

No additional package, ShowOptions field, or callback is required.

Use @suki-sdk/dictation or @suki-sdk/dictation-react v0.1.0-beta.3 or later. For Web SDK Dictation, use the matching release from the same release train. If Dictation is already integrated, you do not install another package.

Content Rewrite requires backend enablement for your organization. You do not configure it in the SDK. If it is not enabled, the rewrite request fails and the UI shows an error. Confirm with Suki that it is enabled before you test with clinicians.

Common use cases

Shorten Long Dictation

After dictating into a note or form field, the clinician selects a long span, chooses Concise, and keeps documenting in the same session.

Expand Short Notes

The clinician selects brief wording, chooses Verbose, and replaces that span in the Dictation editor without starting another session.

Write for Patients

The clinician selects clinical wording, chooses Patient Friendly, and reviews the rewritten span in the hosted UI before they submit.

Rewrite in a Target Field

Use in-field mode so the clinician dictates into a chart field, then rewrites part of that field with the microphone off.

Rewrite in a Scratchpad

Use scratchpad mode so the clinician drafts in the floating panel, rewrites selected text there, then submits the full scratchpad text to your app.

Same Experience in Web SDK Dictation

Web SDK Dictation uses the same hosted iframe, so clinicians get the same rewrite tooltip and styles when Dictation is already in your Web SDK app.

How clinicians use Content Rewrite

The rewrite happens in the Dictation iframe. Your app still receives the full field text through the callbacks you already register.

Open Dictation

The clinician opens Dictation in in-field or scratchpad mode the same way they do today.

Turn Off the Microphone and Select Text

The clinician turns the microphone off, then selects the text they want to change. While the microphone is streaming, the rewrite tooltip stays hidden. The tooltip appears only when the selection has at least two words.

Choose a Rewrite Style

From the rewrite tooltip, the clinician chooses Concise, Verbose, or Patient Friendly. The hosted iframe sends the rewrite request. The UI shows Rewriting…. The clinician can select Cancel while the rewrite runs. Your app does not handle that HTTP call.

Replace the Selection or Retry

On success, Suki replaces only the selected span. The rest of the field stays as it is. If the rewrite fails, the UI shows Rewrite failed. Please try again. with Try again and Cancel. The SDK does not retry on its own.

Submit the Field

When the clinician submits, onSubmit receives { fieldId, text } for the full field value, including any rewritten spans. Optional onDraft works the same way for unfinished text.

ShowOptions and callbacks

Content Rewrite does not change the ShowOptions contract. Pass the same options you pass for any Dictation session.

Option	Required	What changes with Content Rewrite
`mode`	Required	`"in-field"` or `"scratchpad"`
`fieldId`	Required	Echoed on every callback
`rootElement`	Required in JavaScript to show Dictation	Host for the iframe. The React `<Dictation>` component provides its own container
`initialText`	Optional	Starting editor text
`onSubmit`	Required	Receives `{ fieldId, text }`. `text` includes any rewritten text
`onCancel`	Optional	Unchanged
`onDraft`	Optional	Unchanged. Draft text includes any rewritten text

Keep the onSubmit, onDraft, and onCancel callbacks you already register. Content Rewrite does not add a flag on show() or a rewrite-specific handler. The updated field text still arrives through those same callbacks.

Content Rewrite also does not support custom rewrite instructions from your app, and it does not run while the microphone is streaming.

Code examples

The following JavaScript and React code examples use the same Dictation setup you already have. When a clinician rewrites text in the iframe, onSubmit and onDraft receive the updated field text.

JavaScript
React

Pass your usual options to DictationClient.show(). Web SDK Dictation uses the same call with DictationClient from @suki-sdk/js.

JavaScript

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",
  providerId: "YOUR_PROVIDER_ID",
});

const dictationClient = new DictationClient({ authManager });

await dictationClient.show({
  mode: "in-field",
  fieldId: "soap.assessment",
  rootElement: document.getElementById("dictation-root"),
  initialText: existingAssessmentText,
  onSubmit: ({ fieldId, text }) => {
    // text is the full field value, including any Content Rewrite edits
    saveField(fieldId, text);
  },
  onDraft: ({ fieldId, text }) => {
    // Optional: save unfinished text, including rewritten text, for the next show()
    cacheDraft(fieldId, text);
  },
  onCancel: ({ fieldId }) => {
    clearDraft(fieldId);
  },
});

Pass your usual props to <Dictation>. Web SDK Dictation uses the same component from @suki-sdk/react.

React

import { useMemo, useState } from "react";
import { SukiAuthManager } from "@suki-sdk/core";
import { DictationClient } from "@suki-sdk/dictation";
import { Dictation, DictationProvider } from "@suki-sdk/dictation-react";

const authManager = new SukiAuthManager({
  partnerId: "YOUR_PARTNER_ID",
  partnerToken: "YOUR_PARTNER_TOKEN",
  environment: "staging",
  providerId: "YOUR_PROVIDER_ID",
});

function AssessmentField() {
  const client = useMemo(() => new DictationClient({ authManager }), []);
  const [text, setText] = useState("");
  const [open, setOpen] = useState(false);

  return (
    <DictationProvider client={client}>
      <textarea value={text} onChange={(e) => setText(e.target.value)} />
      <button type="button" onClick={() => setOpen(true)}>
        Dictate
      </button>

      {open && (
        <Dictation
          mode="in-field"
          fieldId="soap.assessment"
          initialText={text}
          onSubmit={({ text: next }) => {
            // next includes any Content Rewrite edits from the hosted UI
            setText(next);
            setOpen(false);
          }}
          onCancel={() => setOpen(false)}
          onDraft={({ text: draft }) => setText(draft)}
        />
      )}
    </DictationProvider>
  );
}

Scratchpad mode

Content Rewrite works the same way in scratchpad mode. The clinician turns off the microphone, selects text, and rewrites it in the hosted UI. The final text still arrives on onSubmit.

JavaScript

await dictationClient.show({
  mode: "scratchpad",
  fieldId: "scratchpad",
  rootElement: document.getElementById("scratchpad-root"),
  onSubmit: ({ text }) => {
    insertIntoFocusedField(text);
  },
});

Best practices

Confirm with Suki that Content Rewrite is enabled for your partner before you test with clinicians. The tooltip can still appear; the rewrite call fails if enablement is off.
Keep your existing onSubmit, onDraft, and onCancel handlers. Do not add enableRewrite, onRewrite, or custom rewrite instructions. Content Rewrite does not add ShowOptions fields.
Treat the text on onSubmit and onDraft as the full field, including any rewritten spans. The iframe applies the selection. Your app does not patch offsets.
Rewrite requires the microphone off and a selection of at least two words. While the microphone is streaming, the tooltip stays hidden.
If rewrite fails, the clinician retries from the hosted UI. The SDK does not retry on its own.
If you ship both modes, verify Content Rewrite in in-field and scratchpad. The clinician flow is the same in both.

Next steps

Callbacks - onSubmit, onCancel, and onDraft payload shape. Configuration - Every ShowOptions field. In-field mode - Attach Dictation to a single field. Scratchpad mode - Run Dictation in a floating panel.

Get Started

Integration Guides

Concepts & Feature Guides

Resources

Content Rewrite

Common use cases

Shorten Long Dictation

Expand Short Notes

Write for Patients

Rewrite in a Target Field

Rewrite in a Scratchpad

Same Experience in Web SDK Dictation

How clinicians use Content Rewrite

ShowOptions and callbacks

Code examples

Scratchpad mode

Best practices

Next steps

​Common use cases

Shorten Long Dictation

Expand Short Notes

Write for Patients

Rewrite in a Target Field

Rewrite in a Scratchpad

Same Experience in Web SDK Dictation

​How clinicians use Content Rewrite

​ShowOptions and callbacks

​Code examples

​Scratchpad mode

​Best practices

​Next steps

Common use cases

How clinicians use Content Rewrite

ShowOptions and callbacks

Code examples

Scratchpad mode

Best practices

Next steps