Widget API Reference

This page documents every field Scribeberry accepts and emits for the Partner Widget. For setup and a working example, see Partner Widget.

All postMessage payloads are JSON objects with a required type string. Always verify event.origin === 'https://app.scribeberry.com' (or your configured Scribeberry host) before handling messages.

HTTP: Token endpoint

Mint session tokens server-side only. Never expose your partner key to the browser.

POST https://app.scribeberry.com/api/widget/token
X-Partner-Key: your-partner-id.your-secret
Content-Type: application/json

Request body

Success response

{
  "success": true,
  "data": {
    "token": "eyJ...",
    "expiresAt": "2026-08-12T12:00:00.000Z"
  }
}

Common HTTP errors

EMR → Scribeberry messages

PATIENT_CONTEXT

Send when the chart opens or when the active patient, encounter, or clinical context changes.

{
  type: 'PATIENT_CONTEXT',
  patient: WidgetPatient,           // required
  context?: WidgetMedicalContext,   // optional
  appointment?: WidgetAppointment,    // optional
  noteConfig?: WidgetNoteConfig,      // optional
}

patient (WidgetPatient)

Example — minimum valid patient:

{
  "id": "patient-123",
  "name": "James Wilson"
}

Example — full demographics:

{
  "id": "patient-123",
  "name": "James Wilson",
  "firstName": "James",
  "lastName": "Wilson",
  "dob": "1985-03-15",
  "gender": "male",
  "healthCardNumber": "1234567890",
  "email": "james@example.com",
  "phone": "+1-555-0100"
}

context (WidgetMedicalContext)

All fields are optional. Omit the entire context object if you have no clinical data to send.

allergies[]

medications[]

diagnoses[]

labResults[]

appointment (WidgetAppointment)

noteConfig (WidgetNoteConfig)

Define the shape of structured note output. When provided, template selection is locked to the resolved template for these section labels.

Each section:

Classic SOAP labels (Subjective, Objective, Assessment, Plan) resolve to Scribeberry's curated SOAP template. Other label sets get a synthetic heading-based template. If noteConfig is omitted, SOAP is used.

SET_CONTEXT

Append or replace free-text context outside the structured context object.

{
  type: 'SET_CONTEXT',
  context: string,                    // required
  mode?: 'append' | 'overwrite',     // default: 'append'
}

TOKEN_REFRESH

Extend the session without reloading the iframe.

{
  type: 'TOKEN_REFRESH',
  token: string,   // new JWT from POST /api/widget/token
}

CLOSE_WIDGET

Signal that the user left the chart. Scribeberry may tear down active state.

{
  type: 'CLOSE_WIDGET',
}

Scribeberry → EMR messages

WIDGET_READY

Widget loaded and ready to receive PATIENT_CONTEXT.

{
  type: 'WIDGET_READY',
  version: string,
}

SESSION_STARTED

Sent when an encounter-scoped scribe opens or resumes (emrSessionId was included in the token).

{
  type: 'SESSION_STARTED',
  sessionId: string,   // Scribeberry conversation id — store against your emrSessionId
}

PUSH_NOTE

Clinician sent a generated note to your EMR.

{
  type: 'PUSH_NOTE',
  note: string,                        // full note text — always present
  sections?: Record<string, string>,   // keyed by noteConfig section keys; "" if section not found
  transcript?: string,                 // visit transcript when available
  sessionId: string,                   // Scribeberry conversation id
  patientId: string,                   // your patient.id from PATIENT_CONTEXT
}

Notes can be sent multiple times per session (e.g. after edits).

PUSH_DOCUMENT

Clinician sent a document (letter, referral, form, or PDF).

{
  type: 'PUSH_DOCUMENT',
  title: string,
  content: string,
  documentType: 'letter' | 'referral' | 'form' | 'pdf',
  pdfUrl?: string,
  sessionId: string,
  patientId: string,
}

REQUEST_PATIENT_CONTEXT

Widget needs current patient data. Respond with PATIENT_CONTEXT.

{
  type: 'REQUEST_PATIENT_CONTEXT',
}

TOKEN_EXPIRING

Token will expire soon. Mint a new token and send TOKEN_REFRESH.

{
  type: 'TOKEN_EXPIRING',
  expiresInMs: number,
}

REQUEST_TOKEN_REFRESH

Widget is actively requesting a new token. Respond with TOKEN_REFRESH.

{
  type: 'REQUEST_TOKEN_REFRESH',
}

TOKEN_EXPIRED

Token has expired. Reload the iframe with a new token.

{
  type: 'TOKEN_EXPIRED',
}

WIDGET_ERROR

Validation or processing error. Handle this in your postMessage listener.

{
  type: 'WIDGET_ERROR',
  code: string,
  message: string,
}

The message field contains field-level details, for example:

id: Patient ID is required; gender: Invalid enum value...

Common validation failures:

Patient ID semantics

• patient.id is your EMR identifier. Scribeberry echoes it on PUSH_NOTE.patientId so you can file notes back to the correct chart row.
• Internally, Scribeberry namespaces widget patients as widget_{partnerId}_{patientId} for conversation grouping. Your raw id is never used as a Scribeberry account patient UUID.
• Use stable ids — auto-increment integers are fine as long as they are unique within your EMR and consistent across sessions for the same person.

Enum normalization

These string enums are case-insensitive. Values are trimmed and lowercased before validation:

Unrecognized enum values fail validation with a field-level error in WIDGET_ERROR.message.