AiPlannerVoiceDef Metadata Type in SFDX

Architectural Overview#

When an autonomous Agentforce agent moves from text chat to live telephony channels (Service Cloud Voice), latency, speech cadence, barge-in handling, and acoustic persona become critical architectural concerns. The AiPlannerVoiceDef metadata type defines the voice configuration attached to an Agentforce planner (GenAiPlannerBundle).

By isolating voice synthesis and telephony tuning inside AiPlannerVoiceDef, architects can reuse the same underlying topics and actions across digital chat and voice while tailoring vocal delivery and turn-taking parameters specifically for callers.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .aiPlannerVoiceDef-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AiPlannerVoiceDef xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Natural conversational US English voice profile for the Enterprise Order Support telephony agent.</description>
    <masterLabel>Enterprise Order Support Voice Profile</masterLabel>
    <planner>Enterprise_Order_Support_Planner_v2</planner>
</AiPlannerVoiceDef>

Sample package.xml Manifest#

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

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AiPlannerVoiceDef components via the Salesforce CLI:

# Retrieve all AiPlannerVoiceDef records from the org
sf project retrieve start --metadata "AiPlannerVoiceDef:*"

# Deploy a specific planner voice definition
sf project deploy start --metadata "AiPlannerVoiceDef:Enterprise_Order_Support_Voice_Def"

Senior Architect Best Practices & Gotchas#

• Optimize Action Latency for Voice: Callers on a phone line will not tolerate 15-second silences while an Apex callout runs. Ensure every GenAiFunction invoked by a voice-enabled planner executes in sub-second time or uses progress acknowledgments.
• Avoid Markdown in Voice Outputs: Instruct your voice-enabled GenAiPlugin topics to output concise, spoken-style sentences rather than markdown tables or bulleted lists that sound unnatural when read aloud by text-to-speech engines.

Frequently asked questions

What is the purpose of AiPlannerVoiceDef in Salesforce?

AiPlannerVoiceDef defines the voice synthesis profile, acoustic persona, speaking rate, and interruption handling for an Agentforce planner operating on voice channels.

Where are AiPlannerVoiceDef files stored in an SFDX project?

They are stored in the force-app/main/default/aiPlannerVoiceDefs directory with the .aiPlannerVoiceDef-meta.xml file suffix.

How does AiPlannerVoiceDef connect to a GenAiPlannerBundle?

It references the target planner definition to apply voice-specific synthesis and turn-taking instructions when the agent handles Service Cloud Voice or telephony calls.

How do I retrieve AiPlannerVoiceDef metadata using Salesforce CLI?

Run sf project retrieve start --metadata AiPlannerVoiceDef to fetch all configured planner voice definitions into your SFDX repository.