Service Agentforce Contact Center Coordinate

service-agentforce-contact-center-coordinate: Set up an Agentforce Contact Center voice channel

Coordinates the full path from an authenticated org to a live inbound voice channel: procure a phone number, confirm it is provisioned, and create an active PstnVoice MessagingChannel. The user picks the routing model — Omni Queue (route calls straight to the Agentforce Contact Center queue) or Omni Flow (route to an Agentforce agent via an inbound routing flow, with the queue as fallback). The Omni Queue path only orchestrates the Number Management and MessagingChannel REST APIs. The Omni Flow path can additionally author/publish/activate an Agentforce agent and deploy its inbound (Copilot) and escalation (QueueBased) RoutingFlow flows before wiring the channel.

Scope

• In scope: fetching available numbers, procuring a number, resolving its CommunicationChannelLine, verifying/reconciling live status, choosing the routing model, creating and activating a PstnVoice MessagingChannel (queue- or flow-routed), and — for the Omni Flow path — authoring/publishing/activating an Agentforce agent and deploying its inbound and escalation RoutingFlow flows. Ends with a setup summary.
• Out of scope: authenticating or provisioning the org (the target org must already be authenticated), enabling the Agentforce/Einstein Service Agent toggle (an org preference the operator flips — see references/agentforce-prerequisite.md), outbound/voice-tuning or wiring a pre-existing channel to an agent, and creating non-voice channels.

---

Prerequisites

• Authenticated org — required for every path (this skill never runs an interactive login).
• Omni Flow path only — Einstein and Agentforce Agents must be enabled in the org. Before a voice channel can route to an Agentforce agent, an org admin must turn on Einstein (Setup → Einstein Setup) and then Agentforce Agents (Setup → Einstein → Agentforce / Agents) in the Setup UI. The skill then resolves or provisions the canonical Einstein Agent User (Profile.Name = 'Einstein Agent User') that agent authoring and publish depend on. Do not use generic users whose username/profile merely contains Agent or Bot; those can generate/validate but fail publish. The Omni Queue path has no such prerequisite. Full steps: references/agentforce-prerequisite.md.

---

Required Inputs

Gather or confirm before proceeding:

• Target org: an already-authenticated org. If the user names an alias, use it. If the user refers to their default org (or gives no alias), resolve it with sf org display --json and read result.alias (falling back to result.username); use that value as <alias> for every script. Do not run an interactive login.
• Country: US or CA.
• Phone number type: 10DLC or Toll Free.
• Selected number: chosen by the user from the fetched list.
• Routing model: Omni Queue (default) or Omni Flow. Asked in Step 7.
• (Omni Flow only) Agent source: create a new Agentforce agent + routing flows, or reuse an existing published agent and its inbound routing flow.
• (Omni Flow, new agent only) Agent business context: agent name, agent description (the agent's role/purpose), and company name — passed to sf agent generate agent-spec. The agent name is used as the <label>, and the <apiName> is derived from it (normalization + uniqueness rule in Step 9 sub-step 3); do not prompt for role, website, or API name.

Do not proceed without an authenticated org and both the country and number-type selections. Collect the routing model and any Omni Flow inputs only if/when that path is chosen.

---

Workflow

All steps are sequential. If a step fails, stop and report the error rather than continuing.

1. Confirm the org connection — run sf org display --target-org <alias> --json and read result.instanceUrl. If it fails, ask the user to authenticate the org first, then stop. Do not run an interactive login from this skill.

2. Gather configuration — use AskUserQuestion to collect Country (US/CA) and Phone Number Type (10DLC/Toll Free). Do not mark any option as recommended or default — present the choices neutrally. Wait for both before continuing.

3. Fetch available numbers — read references/number_management_api.md for the endpoint contract, then run scripts/fetch-numbers.sh <alias> <country> <phoneType>. Present the returned numbers as a numbered list and ask the user to select one — do not mark any number as recommended or default.

4. Procure the selected number — run scripts/procure-number.sh <alias> <country> <phoneType> <number>. On a non-2xx response, map the status via references/number_management_api.md and stop with a clear message.

5. Resolve the ChannelLine — run scripts/resolve-channel-line.sh <alias> <number>. It queries CommunicationChannelLine by Code, retrying on empty results. Capture the ChannelLine Id and CodeStatus.

6. Verify the number is live — run scripts/verify-number-live.sh <alias> <number>. It checks CodeStatus via the Tooling API, calls numberStateReconcile when not live, and polls per the strategy in references/verification_and_errors.md. Branch on the exit code: exit 3 (still not Live after polling) → surface the warning and ask whether to wait or proceed; exit 4 (numberStateReconcile returned a non-2xx) → stop and report per the stop-on-non-2xx rule — do not create a channel on top of a failed reconciliation.

7. Choose the routing model — use AskUserQuestion to ask how calls should route, then branch in Step 9:

   • Omni Queue (default) — route directly to the Agentforce Contact Center queue.
   • Omni Flow — route to an Agentforce agent via an inbound routing flow, with the queue as fallback.

8. Resolve the contact center queue — run scripts/resolve-acc-queue.sh <alias> to look up the Agentforce Contact Center default queue Id. Never hardcode a queue Id — it is org-specific. Both models need it: Omni Queue uses it as the channel's SessionHandlerId; Omni Flow uses it as the FallbackQueueId and the escalation-flow target.

9. Create the active voice channel — read references/messaging_channel.md, then follow the branch for the chosen routing model.

   Omni Queue — run scripts/create-voice-channel.sh <alias> <number> <channelLineId> <queueId>. This POSTs a PstnVoice MessagingChannel with SessionHandlerId set to the queue, ChannelLineId set to the resolved CommunicationChannelLine Id, and IsActive: true. Handle the field/status errors documented in that reference.

   Omni Flow — read references/omni-flow-routing.md, then:

   1. Prerequisite gate — run scripts/check-agentforce-prereq.sh <alias> (see references/agentforce-prerequisite.md). Exit 0 → capture the printed canonical Einstein Agent User for --agent-user; the script reuses an existing Einstein Agent User or provisions one with sf org create agent-user. Exit 3 → no canonical user could be found/provisioned, often because the toggle is off or no Agentforce Service Agent User license is available; prompt the user to fix the org and re-run. If the user allows a queue-only fallback, use the Omni Queue create above and note the fallback in the report.
   2. New or existing agent — use AskUserQuestion:
      • Use existing — ask for the published agent's API name/label and its inbound RoutingFlow DeveloperName, then run scripts/resolve-flow-definition.sh <alias> <flowDeveloperName> to get the inbound FlowDefinition Id (300…). resolve-flow-definition.sh verifies only that the flow has an active version, not that the agent is published and Active — confirm the agent's latest BotVersion.Status = 'Active' (SELECT Status FROM BotVersion WHERE BotDefinition.DeveloperName = '<apiName>' ORDER BY VersionNumber DESC LIMIT 1), or tell the user they are responsible for that, before continuing; otherwise the channel is created but calls won't route. Continue at sub-step 5.
      • Create new — continue at sub-step 3.
   3. Author the agent — collect the agent's business context via AskUserQuestion: only agent name, agent description (the agent's role/purpose — this becomes the spec's --role), and company name (do not prompt for role, website, or API name). Use the agent name as the <label>. Derive the <apiName> (it becomes the BotDefinition.DeveloperName and the routing-flow name base) from the agent name: PascalCase the words, keep only alphanumerics, start with a letter (prefix A if needed), cap at 60 chars. Confirm uniqueness via sf data query --query "SELECT DeveloperName FROM BotDefinition WHERE DeveloperName = '<apiName>'" --target-org <alias>; append a numeric suffix on a collision. First prepare the SFDX work dir with scripts/prepare-agent-workdir.sh acc-voice-build; sf agent generate agent-spec requires project context before the authoring-bundle script runs. From inside acc-voice-build, generate the spec: sf agent generate agent-spec --type customer --tone neutral --max-topics 5 --agent-user <einsteinAgentUser> --role "<agent description>" --company-name "<company name>" --output-file specs/<apiName>.yaml --target-org <alias> --json. Then, from the parent/original work dir, run scripts/create-voice-agent.sh <alias> <apiName> <label> acc-voice-build/specs/<apiName>.yaml acc-voice-build, which generates the authoring bundle, fixes the generated default_agent_user, deploys the AiAuthoringBundle, validates, publishes, and activates the agent. Do not switch the planner to Atlas__VoiceAgent — keep the publish-generated Atlas__ConcurrentMultiAgentOrchestration (deviation note in references/omni-flow-routing.md).
   4. Deploy the routing flows — run scripts/create-routing-flows.sh <alias> <apiName> <label> <queueId> <queueName> acc-voice-build. It renders and deploys the inbound (<apiName>_Voice_Omni_Flow, Copilot) and escalation (<apiName>_Voice_Escalation, QueueBased) flows from inside the prepared SFDX work dir, then prints the inbound FlowDefinition Id (300…) on stdout — capture it. Reuse the same acc-voice-build work dir as sub-step 3.
   5. Create the channel — run scripts/create-voice-channel.sh <alias> <number> <channelLineId> <flowDefinitionId> <queueId>. The 5th arg switches the POST to Omni Flow: SessionHandlerId = the inbound FlowDefinition Id, FallbackQueueId = the queue.

10. Confirm setup and write the report — read the created MessagingChannel back. Then write a report using exactly the structure in assets/report-template.md: fill every field with the real value produced during this run (org alias, country, phone-number type, routing model, the commands actually run, the procured number, the resolved CommunicationChannelLine Id and status, the queue resolved by name with its Id, and the created PstnVoice MessagingChannel Id, DeveloperName, ChannelLineId, IsActive, SessionHandlerId, and FallbackQueueId; for Omni Flow also the agent api-name/label and inbound FlowDefinition Id), and end with the one-line Outcome. Include the Omni Flow rows only when that path was taken. One line per item — no extra narrative, and do not omit a field that applies. If a step failed, still fill the fields reached and state the exact error and the step it failed at in Outcome.

---