/service-agentforce-contact-center-coordinate

name: service-agentforce-contact-center-coordinate
description: "Coordinates end-to-end setup of an Agentforce Contact Center voice channel: gathers country and phone-number-type selections, procures a chosen number, resolves its CommunicationChannelLine, verifies the number is live, and creates an active PstnVoice MessagingChannel. The user picks the routing model: Omni Queue (route to the contact center queue) or Omni Flow (route to an Agentforce agent, creating or reusing the agent plus its routing flows). Use when the user asks to set up an Agentforce Contact Center, provision a contact center phone number and voice channel together, or put an Agentforce agent on native voice. TRIGGER when the user says set up agentforce contact center, configure contact center voice, or create a voice channel with omni flow and an agentforce agent. DO NOT TRIGGER when only wiring an existing channel to an existing agent with no number to procure, or creating a non-voice messaging channel."
allowed-tools: Bash(sf org display:*) Bash(sf org create agent-user:*) Bash(sf data query:*) Bash(sf api request rest:*) Bash(sf agent:*) Bash(sf project deploy start:*) Bash(jq:*) Bash(scripts/*) Bash(./scripts/*) Bash(bash scripts/*) Read AskUserQuestion
metadata:
  version: "1.1"
  minApiVersion: "68.0"
  domains: ["Service", "Agentforce"]
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.0.0"

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