service-native-voice-recording-transcription-configure

Native Voice の音声録音と文字起こしを設定する（ヘッドレス）

Native Voice（Thunderbird Voice）の通話録音と通話文字起こしを、組織単位でプログラムから有効または無効にします。Service Console の UI を使用しないヘッドレス／API 主導のサポートセッションにも変更が適用されます。録音と文字起こしは別々の設定です。このスキルでは、指定された状態に一方または両方を設定でき（もう一方は変更しません）、構造化された JSON で確認結果を返します。

対象範囲

• 対象範囲：sf CLI Metadata API のデプロイを使用して、ThunderbirdVoiceSettings メタデータの enableCallRecording および／または enableCallTranscription を指定された状態（true（有効）または false（無効））に設定します（汎用の Settings コンテナー、メンバーは ThunderbirdVoice）。結果の設定を JSON で確認します。ユーザーが指定していない設定は現在の値を維持します。
• 対象外：その他の ThunderbirdVoiceSettings のブール値（通話録音の編集、SIP 録音など）の変更。関連する設定は保持するために読み取りのみ行い、設定も報告もしません。既存の録音や文字起こしに含まれる PII の編集／除去、提供された音声ファイルの文字起こし、Native Voice／Thunderbird チャネル自体のプロビジョニング、Flow、Apex、権限セットの作成は対象外です。これらはこのスキルの範囲外のため、別途対応してください。

---

必要な入力

続行する前に、次の情報を取得または推測してください。

• 対象組織 — sf CLI で認証済みの組織エイリアスまたはユーザー名です。デプロイでは既存の sf ログインを使用します。セッション ID やアクセストークンは求めません。デフォルト：組織のデフォルトターゲット。sf org display -o <alias> で接続を確認してください。
• 対象の設定 — 録音、文字起こし、またはその両方です。デフォルト：両方です。ヘッドレスでのキャプチャでは、通常、録音と文字起こしの両方が必要です。ユーザーが一方だけを指定した場合は、その一方のみを対象とし、もう一方は現在の値を維持します。
• 希望する状態 — 指定した各設定を有効（on／true）にするか、無効（off／false）にするかです。デフォルト：ユーザーが無効化を求めていない限り、有効です。無効化の依頼はそのまま守り、ユーザーが無効にするよう求めた設定を再び有効にしないでください。

---

ワークフロー

すべての手順は順番に実行します。省略したり順序を入れ替えたりしないでください。行き詰まった場合は、停止して不足している組織のコンテキストを確認してください。

1. 2つの設定が別々にモデル化されていることを確認します。 録音 （enableCallRecording）と文字起こし（enableCallTranscription）は、同じメタデータ型の 別個のブール値です。決して1つの統合フラグにまとめないでください。最終確認では、 それぞれを個別に報告する必要があります。

2. 設定スクリプトを実行します。 希望する設定ごとに状態を指定して、 scripts/enable-recording-transcription.sh --target-org <alias> を実行します。 --recording on|off、および／または --transcription on|off を指定します。設定フラグを 指定しない場合、デフォルトで両方をオンにします。例：両方をオフにする → --recording off --transcription off、録音のみを有効にする → --recording on（文字起こしは現状のまま）、文字起こしのみを無効にする → --transcription off。スクリプトは ThunderbirdVoiceSettings（Settings コンテナ経由）を 取得し、組織権限のゲートを確認して、指定されたフラグのみを要求された値に設定し、 それ以外のすべてのフィールドを保持したうえで、ドライランのデプロイで検証し、 デプロイして、ラウンドトリップで確認します。永続化せずに取得と検証を行うには、 --dry-run を使用します。すべてのオプションは scripts/enable-recording-transcription.sh --help を実行して確認してください。

3. Metadata API の仕様については、 references/thunderbird-voice-settings.md を 読んでください。このドキュメントには、型、2つのブール値、Settings コンテナの マニフェスト、v68.0+ のバージョン要件、取得を先に行うゲートチェックが記載されています。 スクリプトが生成するマニフェストテンプレートは assets/package.xml です。

   これは sf CLI Metadata API のデプロイを使用します。生の SOAP 呼び出しではありません。メンバーは mdApiType から Settings サフィックスを除いたもの（ThunderbirdVoice）であり、マニフェストの バージョンは MUST >= 68.0 です。これより低いバージョンでは、フィールドは公開されません。

4. 指定された対象フィールドのみを、要求された状態に変更します。 デプロイする設定ファイルでは、 ユーザーが指定した設定（enableCallRecording および／または enableCallTranscription）のみを、 要求された値（有効にする場合は true、無効にする場合は false）に設定します。それ以外の ThunderbirdVoiceSettings のブール値はすべて、ユーザーが指定していない対象設定も含め、 取得時の値を保持します。他のブール値を追加したり切り替えたりしないでください。また、無効化の 要求を true に戻してはなりません。これらはこのスキルの対象外か、要求に反するものです。

5. 確認用 JSON を返します。 assets/confirmation-output.json に一致する単一の JSON オブジェクトを 出力します。これには、メタデータの type と fullName、ヘッドレス／API デプロイで適用したこと、 そして2つの設定それぞれについて、フィールド名と適用後の有効状態（デプロイ後の現在の状態を示す true／false。変更されたか現状のままかは問いません）を含めます。また、全体の status （ENABLED、DISABLED、または CONFIGURED）も含めます。さらに、取得時の値をそのまま反映した 各兄弟ブール値（例：enableCallRecRedaction、enableSipRecording）の値を含む preserved 配列も含めます。これにより、兄弟フィールドが変更されずに引き継がれたことを 証明します。コンプライアンス上の呼び出し元は、「それ以外は何も変更していない」ことを明示的に確認する 必要があります。兄弟フィールドの値を報告しても、その値を変更したことにはなりません。実行が成功すると、 スクリプトはこのオブジェクトを stdout に出力します。納品物としてそのまま提示してください。 preserved ブロックを削除しないでください。

---

ルール／制約

制約	理由
録音と文字起こしを、別々の設定として扱います	これらは別個のブール値（enableCallRecording、enableCallTranscription）です。ひとつにまとめると、一方だけを有効にする機能が失われ、出力仕様も満たせません。
メンバーが ThunderbirdVoice の汎用 Settings コンテナーを通じてデプロイします	ThunderbirdVoiceSettings は取得可能なトップレベルの型名ではありません。Settings コンテナー（メンバー名 = Settings の接尾辞を除いた mdApiType）が sf CLI のパスであり、組織の sf ログインを使用します。セッション ID は不要です。
マニフェストのバージョンは 68.0 以上である必要があります	ThunderbirdVoiceSettings のフィールドは API v68.0 以降でのみ公開されます。それより低いバージョンでは、取得した型が空、または存在しない状態になります。
デプロイ前に取得し、すべての兄弟フィールドを保持します	デプロイはファイル全体を置き換えます。取得したファイルを基にすることで、ほかの設定を維持し、ゲートの確認もできます。
保持された兄弟フィールドは preserved ブロックで報告しますが、変更はしません	コンプライアンス対応の呼び出し元には、「ほかの項目は変更されていない」という明示的な保証が必要です。確認結果では、取得した各兄弟フィールドの値を変更せずに返します。値を返すことは、その値を設定することではありません。デプロイしたファイルで変更されるのは、指定された対象フィールドのみです。
要求された状態をそのまま反映します。有効化は true、無効化は false です	無効化の要求に対して、設定がひそかに再度有効になったり、有効のまま成功を報告したりするのは、正確性の欠如です。要求どおりの値を設定し、組織から実際に返された値を報告します。
状態を報告する前に、往復確認で検証します	デプロイの「Succeeded」は証明になりません。再取得によって、指定された各設定が要求された値になっていることを確認した後にのみ、結果の状態を報告します。
出力は、単一の有効な JSON オブジェクトにします	この確認結果はヘッドレスの呼び出し元によってプログラムから処理されます。文章だけの回答は使用できません。
出力にセッション ID、アクセストークン、電話番号、録音 URL、文字起こし内容を含めません	これらは機密情報／個人情報です。確認結果では設定状態のみを報告します。

---

注意点

問題	解決方法
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（Settings の接尾辞を除いた mdApiType）を使用してください。完全な型名は取得可能なメンバーではありません。
両方の設定をひとつの切り替え項目（例：recordingAndTranscription: true）にまとめる	デプロイするファイルと確認 JSON の両方で、別個の項目として保持してください。
部分的な設定ファイルをデプロイする	取得したファイルを基にして、兄弟設定の値を維持してください。部分的なファイルでは、それらがリセットされる場合があります。
jq ／ sf がない	スクリプトはこれらに依存します。インストールするか、これらが利用できる環境で実行してください（metadata.cliTools で宣言されています）。

---

出力要件

成果物：

• stdout に、assets/confirmation-output.json の形式に沿った単一の JSON 確認オブジェクトを出力します。 — メタデータの対象、ヘッドレス／API デプロイパス、個別に報告する有効状態付きの 2 つの設定、変更がないことを呼び出し元が確認できるようすべての兄弟ブール値をそのまま返す preserved 配列、および全体の status を含めます。

組織のソースツリーにはファイルを書き込みません。スクリプトは一時的な SFDX プロジェクトで動作し、結果を報告します。

参照ファイル一覧

ファイル	読むタイミング
scripts/enable-recording-transcription.sh	手順 2 — 実行して取得 → 名前付きフィールドを設定 → 検証 → デプロイ → 確認します（--recording on|off、--transcription on|off、--dry-run、--api-version、--help に対応しています。デフォルトでは両方がオンになります）。
references/thunderbird-voice-settings.md	手順 3 — メタデータの種類、2 つのブール値、Settings マニフェスト、v68.0 以上の要件、ゲートチェックについて確認します。
assets/package.xml	手順 3 — スクリプトが生成する Metadata API マニフェストのテンプレートです。内容を確認するか、retrieve/deploy を手動で構築する際に参照します。
assets/confirmation-output.json	手順 5 — 返却する JSON 確認データの正確な形式です。