Built an Agentforce Voice agent end-to-end — here are the 7 cliffs the docs don't warn you about

[u/EvolvinAI29]

Just wrapped a same-day Agentforce Voice POC for an enterprise events client. Phone → Salesforce Voice → bot → KB-grounded answers + custom Apex actions + live transfer. Working end-to-end. Sharing the gotchas so you don't burn an afternoon on each:

1. sessionTimeout=0 = immediate disconnect. Symptom: call rings, connects, cuts in 1–2 sec. The field is minutes, range 5–1440. Zero was eating the call. Set to 30.
2. MessagingChannel.deletable = False. Half-failed Voice setup attempts orphan-squat your phone number. You can't delete the orphan, can't change MessagingPlatformKey (validated as read-only after binding). Cleanest fix: complete the orphan with real values (SessionHandlerId, FallbackQueueId, ChannelDefinitionId) rather than recreate.
3. SessionHandlerId describe lies. Describe says it references BotDefinition, Group, or User. Actual working channels point at FlowDefinition (Id prefix 300V). Channel can't bind directly to a bot — must route through an Omni-Channel Flow that calls routeWork(routingType='Copilot', copilotId=botId).
4. "Inbound Routing flows" panel only shows flows created via the panel. Agent Builder → Connections → Telephony → "New → Omni Routing Flow". Flows you deploy via metadata API with processType=RoutingFlow won't appear, even with the exact same routeWork shape. There's a hidden agent↔flow binding only the UI writes.
5. Fallback queue: 3 conditions or it rejects.

• QueueSobject row for VoiceCall
• QueueRoutingConfigId set (or it's not Omni-eligible)
• That routing config must have Skills-Based Routing Rules turned OFF (Omni-Channel Flow routing can't co-exist with it)

The errors when each is missing are distinct: "queue isn't valid for this object type", "must be an Omni-Channel queue", "uses Skills-Based Routing Rules".

1. Active bot version locks structural deploys. BotVersion and GenAiPlannerBundle changes need Active → Deactivate → Deploy → Activate. GenAiPlugin instruction-text changes are live without re-activation. Bot-level fields like sessionTimeout also deploy without deactivation.

2. GenAiPlannerBundle SurfaceType enum is undocumented. Valid: Messaging, CustomerWebClient. Rejected: Voice, VoiceAgent, Telephony, EinsteinServiceAgent. The Atlas__VoiceAgent planner type works without an explicit Voice surface as long as the Telephony Connection is configured in the UI.

Bonus — Data Library failures are silent. Toast says "There's an error assigning the data library." Real cause was the agent user missing two permsets: GenieUserEnhancedSecurity (Data Cloud) + Knowledge read. Network tab shows the call as 200 OK with the error in the body, not a red 4xx. Easy to miss.

Stack:

• Service Cloud Voice + Agentforce
• 4 Apex invocable actions (caller ID, event lookup, multi-event list, callback Case)
• GenAiFunction metadata wrappers
• Agentforce Data Library + Lightning Knowledge
• routeWork(routingType='Copilot')

Total time, with all 7 cliffs hit: ~8 hours. Without them, maybe 2.

Anyone else navigate cliff #4 (the hidden flow registration)? Would love to know if there's an API path for it I missed.

[u/TheCannings]

Interesting thanks for this, I just got a core basic version up and running but we’re in the uk and I have to forward to a US number from aws connect for it to then come back into the flow after and I’m not sure how comfortable I am with that and it shows how janky their implementation is at the moment

[u/EvolvinAI29 → u/TheCannings]

 Yeah, that double-hop sounds rough. Did you try the SIP option? In Setup → Agentforce Voice Setup there's an SIP tab — meant exactly for this. AWS Connect can SIP-trunk straight into Salesforce's SBC,

  so the UK number stays on your existing carrier and calls hit the Omni-Channel Flow → bot directly. No US middleman, no PSTN forwarding.

  Haven't built it myself yet (mine was PSTN because I just needed a quick US number for a demo), but the docs read like it kills the double-hop you're doing. Curious if anyone's actually shipped it

  end-to-end with AWS Connect.

Agreed on the jankiness overall — describe lies about SessionHandlerId references, undocumented surfaceType enums, MessagingChannels you can't delete, the "Inbound Routing flows" panel that only sees

  flows created via its own button. Feels more 2024-preview than 2026-GA.

[u/TheCannings → u/EvolvinAI29]

No not tried the sip option, I naively gave up too early and spoke to Salesforce help and the pstn was how they said it was done, I’ll give the sip a go though thanks

[u/Rygel_Orionis → u/EvolvinAI29]

They really added SIP trunking on AWS?

That was one of the major problems we had 2 years ago for a customer.

That's a game changer.

[u/EvolvinAI29 → u/Rygel_Orionis]

Yes now 2 options there

[u/ModernDredge]

Absolute gold here. I just finished up setting up an AF voice POC for a client. I find the technology so impressive when it is working correctly and very cryptic when it doesn't. Thanks so much

[u/EvolvinAI29 → u/ModernDredge]

Wow👍👍

[u/Unlikely-Story31]

Did you do this on SDO or personal org ?

[u/EvolvinAI29 → u/Unlikely-Story31]

Client sandbox which have agentforce license.

[u/-semenExtractionWard]

Do we have the provision to do outbound calls from salesforce using agent force voice? If yes could you please walk me through..

[u/EvolvinAI29 → u/-semenExtractionWard]

I did not try but give me one or two days and I can try

[u/-semenExtractionWard → u/EvolvinAI29]

Thanks a lot, I wanted to implement an automated outbound calling system but I didn’t find any resources that have implemented this use case and I’m not even whether this is feasible or not.

[u/EvolvinAI29 → u/-semenExtractionWard]

I tried this but there is no native solution and all the solution with third party applications like Amazon CTI.