Configure Native Voice Recording & Transcription (headless)

Turn call recording and call transcription for Native Voice (Thunderbird Voice) on or off on an org, programmatically, so the change takes effect for headless / API-driven support sessions that never touch the Service Console UI. Recording and transcription are two separate preferences — this skill can set either or both to the requested state (leaving the other untouched) and returns a structured JSON confirmation.

Scope

• In scope: setting enableCallRecording and/or enableCallTranscription to a requested state — true (enable) or false (disable) — on the ThunderbirdVoiceSettings metadata via an sf CLI Metadata API deploy (the generic Settings container, member ThunderbirdVoice); returning a JSON confirmation of the resulting configuration. A preference the user does not name is left at its current value.
• Out of scope: changing any other ThunderbirdVoiceSettings boolean (e.g. call-recording redaction, SIP recording) — siblings are read only to be preserved, never set or reported; redacting/scrubbing PII from existing recordings or transcripts; transcribing a supplied audio file; provisioning the Native Voice / Thunderbird channel itself; authoring Flow, Apex, or permission sets. These are outside this skill's scope — handle them separately.

Required Inputs

Gather or infer before proceeding:

• Target org — an org alias or username the sf CLI is authenticated to. The deploy uses this existing sf login; no session id or access token is requested. Default: the org's default target. Confirm connectivity with sf org display -o <alias>.
• Which preferences — recording, transcription, or both. Default: both, since headless capture typically needs recording and transcription. If the user named just one, target only that one and leave the other at its current value.
• Desired state — enable (on/true) or disable (off/false) for each named preference. Default: enable, unless the user asks to turn something off. Honor a disable request literally — never re-enable a preference the user asked to turn off.

Workflow

All steps are sequential. Do not skip or reorder. If blocked, stop and ask for the missing org context.

1. Confirm the two preferences are modeled separately. Recording (enableCallRecording) and transcription (enableCallTranscription) are distinct booleans on the same metadata type — never collapse them into one combined flag. The final confirmation must report each independently.

2. Run the configure script. Run scripts/enable-recording-transcription.sh --target-org <alias> with the desired state per preference: --recording on|off and/or --transcription on|off. With no preference flags it defaults to turning both on. Examples: turn both off → --recording off --transcription off; enable recording only → --recording on (transcription left as-is); disable transcription only → --transcription off. The script retrieves ThunderbirdVoiceSettings (via the Settings container), checks the org-perm gate, sets only the named flag(s) to the requested value while preserving every other field, validates with a dry-run deploy, deploys, and verifies by round-trip. Use --dry-run to retrieve + validate without persisting. Run scripts/enable-recording-transcription.sh --help for all options.

3. For the Metadata API contract, read references/thunderbird-voice-settings.md — it documents the type, the two booleans, the Settings-container manifest, the v68.0+ version floor, and the retrieve-first gate check. The manifest template the script generates is assets/package.xml.

   This uses the sf CLI Metadata API deploy, not a raw SOAP call. The member is the mdApiType without the Settings suffix (ThunderbirdVoice), and the manifest version MUST be >= 68.0 — the fields are not exposed at any lower version.

4. Change only the named target field(s), to the requested state. The deployed settings file sets exactly the preference(s) the user named — enableCallRecording and/or enableCallTranscription — to the requested value (true to enable, false to disable); every other ThunderbirdVoiceSettings boolean, INCLUDING a target preference the user did not name, keeps its retrieved value. Do not add or flip other booleans, and never coerce a disable request back to true — they are out of this skill's scope or contrary to the request.

5. Return the confirmation JSON. Emit a single JSON object matching assets/confirmation-output.json: the metadata type and fullName, that it was applied via a headless/API deploy, and — for each of the two preferences separately — its field name and its resulting enabled state (true/false, as it now stands after the deploy, whether it was changed or left as-is), plus an overall status (ENABLED, DISABLED, or CONFIGURED). It also includes a preserved array echoing every sibling boolean (e.g. enableCallRecRedaction, enableSipRecording) with the value it was retrieved with — this attests the siblings were carried through unchanged, which compliance callers need as explicit "nothing else moved" assurance. Reporting a sibling's value is NOT changing it. On a successful run the script prints this object on stdout; surface it verbatim as the deliverable — do not strip the preserved block.

Rules / Constraints

Gotchas

Output Expectations

Deliverables:

• A single JSON confirmation object on stdout, shaped per assets/confirmation-output.json — the metadata target, the headless/API deploy path, each of the two preferences reported separately with its enabled state, a preserved array echoing every sibling boolean (unchanged) so callers can confirm nothing else moved, and an overall status.

No files are written to the org's source tree — the script works in a temporary SFDX project and reports the result.

Reference File Index