Integrate the SDK › Implementation

Build the form object

Every session takes one form object — the whole contract between your code and Speechineer. It comes in two shapes, and which one you write depends on where you defined the form — configured in the workspace or defined in code — and each has its own section below.

From your workspace

A form configured in Speechineer: your code names it, and the fields, prompts and models come from your workspace — change them there without shipping a release. Individual fields can be marked in your workspace as set by code, and those arrive through fieldConfigs.

Options

What the object names:

Note

Pin a published version: the workspace can keep drafting the next one while production runs on v1, and you move over by changing one string.

Additional information in

Configure the form › In the workspace

Configuration set by code

Fields your workspace form marks as set by your code take their configuration from fieldConfigs — a choice field whose options come from your own data, for example. What to extract is already written in your workspace, so only the field id and the configuration come from here, built with FormFieldConfig. Three field types take a configuration — the rest have nothing for code to supply:

Field type	Built with	Configuration from code
select	FormFieldConfig.select(id, options, appendOptionsToPrompt?)	The single-choice options, a non-empty list; optionally append them to the prompt so the extraction sees them as part of the instruction.
multiselect	FormFieldConfig.multiselect(id, options, appendOptionsToPrompt?)	The multi-choice options — same rules as select.
slider	FormFieldConfig.slider(id, [min, max])	The numeric range the value may take, with min below max.

Note

Fields marked as Set by your code in your workspace form are the only ones read from fieldConfigs — one of them missing stops the session from starting — and every other field keeps the definition it has in your workspace.

Additional information in

Configure the form › In the workspace › Define the form › Options

Example

An example — a patient-intake form, pinned to its published version, with its two fields set by code:

// A form configured in your workspace — your code only names it.
import { FormFieldConfig } from "@speechineer/react";

const intakeForm = {
  source: "workspace",
  key: "spnr_intake_001",   // the form ID, shown beside the form's name in the workspace
  version: "v1",            // a PUBLISHED version's key — pin it
  language: "en",           // which language of that version
  // Only for fields the workspace marks as "set by code":
  fieldConfigs: [
    FormFieldConfig.select("insurance", ["None", "Public", "Private"]),
    FormFieldConfig.slider("pain_level", [0, 10]),
  ],
};

// A form configured in your workspace — your code only names it.
import { FormFieldConfig } from "@speechineer/angular";

const intakeForm = {
  source: "workspace",
  key: "spnr_intake_001",   // the form ID, shown beside the form's name in the workspace
  version: "v1",            // a PUBLISHED version's key — pin it
  language: "en",           // which language of that version
  // Only for fields the workspace marks as "set by code":
  fieldConfigs: [
    FormFieldConfig.select("insurance", ["None", "Public", "Private"]),
    FormFieldConfig.slider("pain_level", [0, 10]),
  ],
};

// A form configured in your workspace — your code only names it.
import { FormFieldConfig } from "@speechineer/js";

const intakeForm = {
  source: "workspace",
  key: "spnr_intake_001",   // the form ID, shown beside the form's name in the workspace
  version: "v1",            // a PUBLISHED version's key — pin it
  language: "en",           // which language of that version
  // Only for fields the workspace marks as "set by code":
  fieldConfigs: [
    FormFieldConfig.select("insurance", ["None", "Public", "Private"]),
    FormFieldConfig.slider("pain_level", [0, 10]),
  ],
};

From your code

The object is exactly the one described in Configure the form › In code — its identity, its fields built with FormField, its prompts and its models. Nothing changes when you use it here: pass it as the session's form, and Speechineer records it in your workspace the first time a session starts.

Options

What the object carries:

Additional information in

Configure the form › In code

Example

The same example, its fields shipped by your code:

// A form defined in code — your code ships the fields; Speechineer records it under its key.
import { FormField } from "@speechineer/react";

const intakeForm = {
  source: "inline",
  key: "patient-intake",    // your own stable identifier
  version: "v1",
  language: "en",
  fields: [
    FormField.text("full_name", "Extract the patient's full name."),
    FormField.date("date_of_birth", "Extract the date of birth."),
    FormField.select("insurance", "Extract the insurance type.", ["None", "Public", "Private"]),
    FormField.slider("pain_level", "Rate the pain from 0 to 10.", [0, 10]),
  ],
  prompts: { transcription: "Patient intake: expect medical terms and medication names." }, // optional
};

// A form defined in code — your code ships the fields; Speechineer records it under its key.
import { FormField } from "@speechineer/angular";

const intakeForm = {
  source: "inline",
  key: "patient-intake",    // your own stable identifier
  version: "v1",
  language: "en",
  fields: [
    FormField.text("full_name", "Extract the patient's full name."),
    FormField.date("date_of_birth", "Extract the date of birth."),
    FormField.select("insurance", "Extract the insurance type.", ["None", "Public", "Private"]),
    FormField.slider("pain_level", "Rate the pain from 0 to 10.", [0, 10]),
  ],
  prompts: { transcription: "Patient intake: expect medical terms and medication names." }, // optional
};

// A form defined in code — your code ships the fields; Speechineer records it under its key.
import { FormField } from "@speechineer/js";

const intakeForm = {
  source: "inline",
  key: "patient-intake",    // your own stable identifier
  version: "v1",
  language: "en",
  fields: [
    FormField.text("full_name", "Extract the patient's full name."),
    FormField.date("date_of_birth", "Extract the date of birth."),
    FormField.select("insurance", "Extract the insurance type.", ["None", "Public", "Private"]),
    FormField.slider("pain_level", "Rate the pain from 0 to 10.", [0, 10]),
  ],
  prompts: { transcription: "Patient intake: expect medical terms and medication names." }, // optional
};

Warning

The contract that fails silently: recognized values arrive keyed by field id. If an id on the form and an id in your rendering code disagree, that field simply never fills — no error, anywhere. When fields stay empty, log values and compare its keys against your markup before debugging anything else.