VoiceSettings Metadata Type in SFDX

Architectural Overview#

The VoiceSettings metadata type manages organization-level telephony configurations for Salesforce Service Cloud Voice. Traditionally, computer telephony integration (CTI) relied on fragile browser popups and disjointed third-party softphones. Service Cloud Voice unifies phone channels natively inside the Salesforce console, integrating directly with telephony providers like Amazon Connect or Bring Your Own Telephony (BYOT) partners.

From an enterprise contact center architecture perspective, VoiceSettings serves as the programmatic foundation that activates audio streaming, enables real-time speech-to-text transcription for Einstein Conversation Insights, and governs compliance recording controls. Automating these settings across CI/CD environments ensures that omni-channel routing and telephony behaviors remain uniform across all developer and staging environments.

Directory and File Conventions#

In Salesforce DX project structures, VoiceSettings is stored as a singleton settings file in the settings/ directory.

Key Metadata Fields#

The VoiceSettings XML schema defines the following core telephony parameters:

Declarative XML and Package Manifest Examples#

Below is an enterprise XML declaration configured for real-time contact center intelligence:

<?xml version="1.0" encoding="UTF-8"?>
<VoiceSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableRealtimeCallTranscription>true</enableRealtimeCallTranscription>
    <enableServiceCloudVoice>true</enableServiceCloudVoice>
    <enableVoiceCallRecording>true</enableVoiceCallRecording>
    <enableVoiceConferencing>true</enableVoiceConferencing>
</VoiceSettings>

Scratch Org Configuration (project-scratch-def.json)#

To enable telephony features in partner or developer scratch orgs:

{
  "orgName": "Voice Contact Center Dev",
  "edition": "Enterprise",
  "features": ["ServiceCloudVoice"],
  "settings": {
    "voiceSettings": {
      "enableServiceCloudVoice": true,
      "enableRealtimeCallTranscription": true,
      "enableVoiceCallRecording": true
    }
  }
}

Manifest Definition (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Voice</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage VoiceSettings using standard Salesforce CLI commands:

# Retrieve Voice settings from the target org
sf project retrieve start --metadata Settings:Voice

# Deploy Voice settings to a staging or production org
sf project deploy start --metadata Settings:Voice --target-org prod-voice

Architect Best Practices and Gotchas#

• Contact Center Certificate Dependencies: Deploying VoiceSettings enables the platform; however, contact centers must be paired with Amazon Connect instances and AWS Identity and Access Management (IAM) role trusts.
• Data Residency and Recording Privacy: Telephony call recordings frequently contain sensitive customer audio. Verify that audio storage buckets comply with regional data sovereignty standards (e.g., GDPR, CCPA).
• Omni-Channel Flow Orchestration: Pair VoiceSettings with Omni-Channel Flows to dynamically route inbound phone calls based on customer tier and agent skill matrices.

Frequently asked questions

What does VoiceSettings configure in Salesforce Service Cloud?

It configures Service Cloud Voice telephony capabilities, live call transcription engines, call recording policies, and agent softphone integration controls.

How do you retrieve VoiceSettings using the Salesforce CLI?

Run sf project retrieve start with the metadata flag set to Settings:Voice to pull Voice.settings-meta.xml into your project settings directory.

Does Service Cloud Voice require Amazon Connect or partner telephony?

Yes, Service Cloud Voice integrates with Amazon Connect natively or partner telephony vendors such as Genesys Cloud, Vonage, and Five9 through BYOT connectors.

What happens if VoiceSettings is deployed to an org without Voice licenses?

The deployment will fail with an error indicating that Service Cloud Voice feature licenses are missing or unentitled in the destination environment.