Dictation and recovery

Bombyx uses one dictation component for assistant messages, family updates and private call instructions. Dictation creates editable text. It does not send a message or instruction, confirm an update, or start a call.

Controls and saved drafts

Press the microphone to record. The recording bar shows the timer, Finish and Cancel. After Finish, the same control shows preparation, transcription and any retry. Microphone permissions, connection failures and no-speech results have visible explanations.

Unfinished audio and text can stay on the same browser for up to 24 hours. Reopening offers Resume or Discard. New chat, sign-out, identity changes and configured shared-device clearing remove affected recovery data sooner. Browser storage may be blocked or evicted; a visible warning explains when the page must remain open. Another device cannot recover a browser’s recording.

Version 2 request contract

Use the existing widget endpoint POST /api/widget/{key}/dictation, or the WordPress plugin’s existing local dictation proxy. Keep the normal widget/site authorization, current action tokens and signed WordPress proxy fields. Recovery never bypasses those checks.

The request is multipart form data:

Field	Value
dictation_protocol	2
dictation_action	transcribe or status
request_id	Stable UUID generated before the first upload
recovery_key	Cryptographically random 64-character lowercase hex value, saved privately before upload
audio	Required only for transcribe; the original recording bytes
duration_seconds	Existing duration field for transcribe; omit for status
Existing context/auth fields	Keep the current widget, token, page and frame contract

Keep the same recording ID, private key and audio bytes when retrying. Never put the key in a URL, analytics event or log. A visitor ID is not proof that the visitor owns a recovered result.

A completed request returns the existing text field plus state: completed. HTTP 202 with state: processing means wait for retry_after, then check status using the same POST endpoint. Status does not contact the transcription provider. Errors include a safe message, retryable, optional retry_after and attempts_exhausted.

The server permits three paid attempts per recording. Replaying a completed request returns the saved text without another paid call. An active attempt must finish or reach its deadline before another can start. Authentication failure, invalid media, no speech and spending limits require the stated action rather than blind retries. An expired recording ID cannot restart its paid-attempt count.

The browser makes at most five transport requests per automatic round. Offline pauses recovery. Manual retry keeps the server’s attempt count. Exhausted recordings remain available locally for playback/download/discard.

The server does not archive audio. Recovery text is encrypted, unavailable after 24 hours and removed by expiry cleanup. See the OpenAPI recovery contract.

Compatibility and installation

Existing clients without protocol version 2 keep their current response contract during rollout. Current app and WordPress distributions are generated from the same source; plugin installation must include dictation-core.js and dictation.css alongside the frontend adapter. Do not copy a separate recorder into a custom integration.