service-native-voice-recording-transcription-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enable Native Voice Recording & Transcription (headless)

以无界面方式启用Native Voice录音与转录

Turn on call recording and call transcription for Native Voice (Thunderbird Voice) on an org, programmatically, so they take effect for headless / API-driven support sessions that never touch the Service Console UI. Recording and transcription are two separate preferences — this skill enables both and returns a structured JSON confirmation.

通过编程方式在组织中为Native Voice（Thunderbird Voice）开启录音和转录功能，使其在从未接触Service Console UI的无界面/API驱动支持会话中生效。录音和转录是两个独立的偏好设置——此技能会同时启用两者，并返回结构化的JSON确认信息。

Scope

范围

In scope: enabling
```
enableCallRecording
```
and
```
enableCallTranscription
```
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.
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.

包含范围：通过sf CLI Metadata API部署（通用
```
Settings
```
容器，成员为
```
ThunderbirdVoice
```
）在
```
ThunderbirdVoiceSettings
```
元数据上启用
```
enableCallRecording
```
和
```
enableCallTranscription
```
；返回配置结果的JSON确认信息。
排除范围：修改任何其他
```
ThunderbirdVoiceSettings
```
布尔值（如通话录音编辑、SIP录音）——这些关联设置仅可读取以保留原有状态，绝不进行设置或上报；从现有录音或转录文本中编辑/清除PII；转录提供的音频文件；配置Native Voice/Thunderbird渠道本身；编写Flow、Apex或权限集。这些均超出此技能的范围——需单独处理。

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. Confirm only if the user named just one.

在执行前需收集或推断：

目标组织——sf CLI已认证的组织别名或用户名。部署将使用现有的
```
sf
```
登录信息；无需请求会话ID或访问令牌。默认值：组织的默认目标。可通过
```
sf org display -o <alias>
```
确认连接性。
需启用的偏好设置——录音、转录，或两者都启用。默认值：两者都启用，因为无界面捕获通常同时需要录音和转录。仅当用户明确指定其中一项时才需确认。

Workflow

工作流程

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

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.
Run the enable script. Run
```
scripts/enable-recording-transcription.sh --target-org <alias>
```
. It retrieves
```
ThunderbirdVoiceSettings
```
(via the
```
Settings
```
container), checks the org-perm gate, flips the two target flags to
```
true
```
while preserving every sibling, 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.
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.
Change only the two target fields. The deployed settings file sets exactly
```
enableCallRecording
```
and
```
enableCallTranscription
```
to
```
true
```
; every other
```
ThunderbirdVoiceSettings
```
boolean keeps its retrieved value. Do not add or flip other booleans — they are out of this skill's scope.
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 enabled state, plus an overall
```
status
```
. 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.

所有步骤需按顺序执行，不得跳过或重新排序。若受阻，请停止并询问缺失的组织上下文信息。

确认两项偏好设置为独立配置。录音（
```
enableCallRecording
```
）和转录（
```
enableCallTranscription
```
）是同一元数据类型下的独立布尔值——绝不能将它们合并为一个组合标志。最终的确认信息必须分别上报每一项的状态。
运行启用脚本。执行
```
scripts/enable-recording-transcription.sh --target-org <alias>
```
。该脚本会检索
```
ThunderbirdVoiceSettings
```
（通过
```
Settings
```
容器），检查组织权限网关，将两个目标标志设为
```
true
```
同时保留所有关联设置，通过试运行部署进行验证，完成部署，并通过往返验证确认结果。使用
```
--dry-run
```
参数可仅检索并验证，不保存更改。执行
```
scripts/enable-recording-transcription.sh --help
```
查看所有选项。
关于Metadata API约定，请阅读
```
references/thunderbird-voice-settings.md
```
——其中记录了元数据类型、两个布尔值、
```
Settings
```
容器清单、**v68.0+**的版本下限，以及检索前的网关检查。脚本生成的清单模板为
```
assets/package.xml
```
。
此操作使用sf CLI Metadata API部署，而非原始SOAP调用。成员为mdApiType（不含
```
Settings
```
后缀，即
```
ThunderbirdVoice
```
），且清单版本必须**>= 68.0**——低于此版本的字段不会被暴露。
仅修改两个目标字段。部署的设置文件仅将
```
enableCallRecording
```
和
```
enableCallTranscription
```
设为
```
true
```
；所有其他
```
ThunderbirdVoiceSettings
```
布尔值保持其检索到的原始值。不得添加或修改其他布尔值——这些超出此技能的范围。
返回确认JSON。输出一个符合
```
assets/confirmation-output.json
```
格式的JSON对象：包含元数据
```
type
```
和
```
fullName
```
、通过无界面/API部署应用的信息，以及——针对每一项偏好设置——其字段名称和启用状态，还有整体
```
status
```
。此外还包含一个**
```
preserved
```
**数组，回显所有关联布尔值（如
```
enableCallRecRedaction
```
、
```
enableSipRecording
```
）及其检索到的原始值——这可向合规调用者明确证明关联设置未被修改。上报关联设置的值并不等同于修改它们。脚本运行成功时会在标准输出打印此对象，请直接原样展示作为交付结果——不要移除
```
preserved
```
块。

Rules / Constraints

规则/约束

Constraint	Rationale
Model recording and transcription as two separate preferences	They are distinct booleans ( `enableCallRecording` , `enableCallTranscription` ); collapsing them loses the ability to enable one without the other and fails the output contract.
Deploy through the generic `Settings` container with member `ThunderbirdVoice`	`ThunderbirdVoiceSettings` is not a retrievable top-level type name; the `Settings` container (member = mdApiType minus the `Settings` suffix) is the sf CLI path and uses the org's `sf` login — no session id.
Manifest version must be >= 68.0	`ThunderbirdVoiceSettings` fields are only exposed at API v68.0+; below that the retrieve returns the type empty/absent.
Retrieve before deploy; preserve all sibling fields	The deploy is a full-file replace — starting from the retrieved file keeps other prefs intact and lets the gate be checked.
Report the preserved siblings in a `preserved` block, but never change them	Compliance callers need explicit "nothing else moved" assurance; the confirmation echoes each sibling's retrieved value unchanged. Echoing a value is not setting it — the deployed file still flips only the two target fields.
Verify by round-trip before reporting `ENABLED`	A "Succeeded" deploy is not proof; only claim enabled after a re-retrieve returns both `true` .
Output must be a single valid JSON object	The confirmation is consumed programmatically by headless callers; prose-only answers are not usable.
Do not include a session id, access token, phone number, recording URL, or transcript content in the output	These are secrets / PII; the confirmation reports configuration state only.

约束	理由
将录音和转录视为两个独立的偏好设置	它们是独立的布尔值（ `enableCallRecording` 、 `enableCallTranscription` ）；合并会失去单独启用其中一项的能力，且不符合输出约定。
通过通用 `Settings` 容器（成员为 `ThunderbirdVoice` ）进行部署	`ThunderbirdVoiceSettings` 并非可检索的顶级类型名称； `Settings` 容器（成员=mdApiType去掉 `Settings` 后缀）是sf CLI的操作路径，且使用组织的 `sf` 登录信息——无需会话ID。
清单版本必须>=68.0	`ThunderbirdVoiceSettings` 字段仅在API v68.0+版本中暴露；低于此版本时，检索会返回空类型或不存在该类型。
部署前先检索；保留所有关联字段	部署是全文件替换——从检索到的文件开始操作可保持其他偏好设置不变，并能检查网关状态。
在 `preserved` 块中上报保留的关联设置，但绝不修改它们	合规调用者需要明确的“无其他更改”保证；确认信息会回显每个关联设置的原始值。回显值并不等同于设置值——部署文件仍仅修改两个目标字段。
往返验证后再上报 `ENABLED` 状态	“部署成功”并不代表配置生效；仅当重新检索返回两项均为 `true` 时，才可声称已启用。
输出必须是单个有效的JSON对象	确认信息由无界面调用者以编程方式消费；仅用文本描述的答案无法使用。
输出中不得包含会话ID、访问令牌、电话号码、录音URL或转录内容	这些属于机密信息/PII；确认信息仅上报配置状态。

Gotchas

常见问题

Issue	Resolution
`Property 'enableCallRecording' not valid in version <N>` / `Settings type 'ThunderbirdVoice' is unknown`	API version too low. The fields are only exposed at v68.0+. Raise `--api-version` to 68.0 or higher — this is NOT a feature gate.
Retrieve returns an empty `<ThunderbirdVoiceSettings/>` (no fields)	Org-perm gate `orgHasNativeVoiceAllowed` is off — Native Voice is not provisioned. Enable via provisioning/Blacktab; metadata cannot flip an unprovisioned feature.
Trying to retrieve `ThunderbirdVoiceSettings` as the type name	Use the `Settings` container with member `ThunderbirdVoice` (mdApiType minus the `Settings` suffix); the full type name is not a retrievable member.
Collapsing both prefs into one toggle (e.g. `recordingAndTranscription: true` )	Keep two distinct entries in both the deployed file and the confirmation JSON.
Deploying a partial settings file	Start from the retrieved file so sibling prefs keep their values; a partial file can reset them.
Missing `jq` / `sf`	The script depends on them; install or run in an environment that has them (declared in `metadata.cliTools` ).

问题	解决方案
`Property 'enableCallRecording' not valid in version <N>` / `Settings type 'ThunderbirdVoice' is unknown`	API版本过低。字段仅在v68.0+版本中暴露。将 `--api-version` 提升至68.0或更高版本——这并非功能网关限制。
检索返回空的 `<ThunderbirdVoiceSettings/>` （无字段）	组织权限网关 `orgHasNativeVoiceAllowed` 未开启——Native Voice未配置。需通过配置/Blacktab启用；元数据无法启用未配置的功能。
尝试以 `ThunderbirdVoiceSettings` 作为类型名称进行检索	使用 `Settings` 容器，成员为 `ThunderbirdVoice` （mdApiType去掉 `Settings` 后缀）；完整类型名称并非可检索的成员。
将两项偏好设置合并为一个开关（如 `recordingAndTranscription: true` ）	在部署文件和确认JSON中均保留两个独立的条目。
部署部分设置文件	从检索到的文件开始操作，以保持关联偏好设置的原始值；部分文件可能会重置这些设置。
缺少 `jq` / `sf`	脚本依赖这些工具；需安装它们或在已安装的环境中运行（已在 `metadata.cliTools` 中声明）。

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.

交付成果：

标准输出中的单个JSON确认对象，格式符合
```
assets/confirmation-output.json
```
——包含元数据目标、无界面/API部署路径、分别上报的两项偏好设置及其启用状态、回显所有关联布尔值（未修改）的
```
preserved
```
数组（以便调用者确认无其他更改），以及整体
```
status
```
。

不会向组织的源代码树写入任何文件——脚本在临时SFDX项目中运行并上报结果。

Reference File Index

参考文件索引

File	When to read
`scripts/enable-recording-transcription.sh`	Step 2 — run to retrieve → flip → validate → deploy → verify (supports `--dry-run` , `--api-version` , `--help` ).
`references/thunderbird-voice-settings.md`	Step 3 — for the metadata type, the two booleans, the `Settings` manifest, the v68.0+ floor, and the gate check.
`assets/package.xml`	Step 3 — the Metadata API manifest template the script generates; read to understand or hand-build the retrieve/deploy.
`assets/confirmation-output.json`	Step 5 — the exact shape of the JSON confirmation to return.

文件	阅读时机
`scripts/enable-recording-transcription.sh`	步骤2——执行以完成检索→修改→验证→部署→验证（支持 `--dry-run` 、 `--api-version` 、 `--help` 参数）。
`references/thunderbird-voice-settings.md`	步骤3——了解元数据类型、两个布尔值、 `Settings` 清单、v68.0+版本下限，以及网关检查。
`assets/package.xml`	步骤3——脚本生成的Metadata API清单模板；阅读以理解或手动构建检索/部署操作。
`assets/confirmation-output.json`	步骤5——需返回的JSON确认信息的精确格式。