Fill with voice

Use case: fill the same FieldStore from a microphone. Two modes, one mint operation.

Hosted WebView / iframe bridge

Native and JS hosts do not implement Realtime. They load /voice-bridge.html with a short-lived integration_token. That page iframes {sdkOrigin}/embed/forms/fill, which is the capture engine.

https://docs.comprehendly.nz/voice-bridge.html
  ?integration_token=scist_…
  &page_id={uuid}
  &fill_mode=assistant   # or silent
  &base_url=https://sdk.comprehendly.nz

JavaScript:

import { mountVoiceBridge } from '@comprehendly/forms'

mountVoiceBridge('#voice', {
  token: client.accessToken,
  pageId,
  mode: 'assistant',
  store: client.store
})

Swift (iOS):

let url = try client.voiceBridgeURL(pageId: pageId, mode: "assistant")
VoiceBridgeView(url: url, store: client.store)

The WebView must grant microphone capture. Add NSMicrophoneUsageDescription to the host Info.plist. Exchange still uses your allowlisted native origin (e.g. https://ios-demo.comprehendly.nz); the token is then passed into the bridge.

The fill embed posts stepcare:fields_updated with field_values as the user or voice writes, and stepcare:submission_saved (including fieldValues) on save. FieldStore hydrates either camelCase or snake_case. Requires Forms SDK / embed deploy that includes this message (forms.js v1.3).

Mint without the widget

Gateway forms.voice.start (SDK session.start).

await client.session.start({
  pageId,
  mode: 'assistant', // or 'silent'
  uiConsentGranted: true,
  assistantContext: { subject_name: 'Alex', purpose: 'Check-in' }
})

Response data includes client_secret, session_mode, form_voice_session_id, expires_at.

Connect that secret to the hosted Realtime client. In the browser, the iframe fill UI and forms.js already do this. Native: load a WebView pointed at the SDK origin; do not implement gpt-realtime yourself in v1.

Modes

mode	When to use
`silent`	Passive listening / dictation. No spoken agent.
`assistant`	Spoken walkthrough of the published page (same script family as phone fill).

Consent

If your UI already collected recording consent, pass ui_consent_granted: true (SDK default). If not, pass false and do not start audio until the user accepts.

Status in these SDKs

JS: mountVoiceBridge + demo Assistant/Silent buttons.
Swift: VoiceBridgeView WKWebView; demo sheet.

Until production sdk.comprehendly.nz ships forms.js v1.3, pass a preview base_url / sdkOrigin so FieldStore hydrates from stepcare:fields_updated.