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. --- ## Rules / Constraints | Constraint | Rationale | |-----------|-----------| | Never run an interactive login; require a pre-authenticated org alias | Auth and org lifecycle are out of scope; keeps the skill portable across surfaces | | Call APIs via `sf api request rest`; never extract the access token | Uses the CLI's stored session for `--target-org` — no raw token handling | | Never hardcode a queue Id / `SessionHandlerId` / `FlowDefinition` Id | These are org-specific; always resolve them (queue in Step 8, flow via `resolve-flow-definition.sh`) | | Attach routing via `SessionHandlerId` (+ `FallbackQueueId` for Omni Flow) — not `TargetQueueId` or `RoutingType` | Omni Queue: `SessionHandlerId` = queue Id. Omni Flow: `SessionHandlerId` = inbound `FlowDefinition` Id (`300…`), `FallbackQueueId` = queue Id | | Omni Flow: publish **and** activate the agent and deploy the inbound flow (Active, `300`-prefix) before creating the channel | The channel's `SessionHandlerId` points at a live inbound `FlowDefinition` that references a published, active agent | | Do not switch the agent's `plannerType` to `Atlas__VoiceAgent` | This org rejects it with an opaque error; keep the publish-generated `Atlas__ConcurrentMultiAgentOrchestration` — voice still routes via the `Copilot` flow (deviation) | | If the Agentforce prerequisite is unmet or agent/flow creation fails, stop and report unless the user explicitly accepts the Omni Queue fallback | Some runs require a new Agentforce agent and Omni Flow channel; do not silently downgrade the routing model | | Use `ChannelLineId` (not scalar `ChannelLine`) to link the CommunicationChannelLine | `ChannelLine` is the relationship name; the writable create field is `ChannelLineId` | | `MessageType` must be `PstnVoice` and `IsActive: true` | Required for an active inbound voice channel | | Do not set `IsoCountryCode` on `PstnVoice` channels | Not valid for this channel type | | Stop and report on any non-2xx API response | Partial setup left silent is worse than a clear failure | --- ## Gotchas | Issue | Resolution | |-------|------------| | `ChannelLine` not found immediately after procurement | Records propagate asynchronously — retry with backoff (Step 5 script handles this) | | Number `CodeStatus` not `Live` | Call `numberStateReconcile` and poll (Step 6 script); warn if it stays provisioning | | `INVALID_FIELD: The value provided for foreign key reference ChannelLine is not a nested SObject` on channel create | The relationship name `ChannelLine` was sent as a scalar field — send the Id in `ChannelLineId` | | `FIELD_INTEGRITY_EXCEPTION` blocking a non-live number | Expected when validation is enforced — wait for the number to become live, then retry | | Duplicate `DeveloperName` | A channel with that name exists — derive a unique name or reuse the existing channel | | Spaces in `phoneNumberType` (`Toll Free`) | URL-encode when building query strings (scripts handle this) | | `sf agent generate agent-spec` fails with `RequiresProjectError` | Run `scripts/prepare-agent-workdir.sh acc-voice-build`, then invoke `sf agent generate agent-spec` from inside `acc-voice-build` with `--output-file specs/<apiName>.yaml` | | `sf agent publish` says `default agent user NEW AGENT USER` | The generator left a placeholder in the `.agent` file — `create-voice-agent.sh` patches `default_agent_user` from the spec's `agentUser` before deploy/publish | | `sf agent publish` says `Unable to access the Salesforce Agent APIs` or `User doesn't have access to use agent` | Usually the spec/bundle used a generic Agent/Bot-profile user. Run `scripts/check-agentforce-prereq.sh`; it must return a user whose profile is exactly `Einstein Agent User` | | Opaque server error (e.g. `-1103525358`) when publishing/validating the agent | Caused by setting `plannerType: Atlas__VoiceAgent` — remove it and keep `Atlas__ConcurrentMultiAgentOrchestration` (deviation; `create-voice-agent.sh` never touches the planner) | | Routing flow deploy fails with `does not contain a valid Salesforce DX project` | Use the same prepared `acc-voice-build` work dir; `create-routing-flows.sh` now runs `sf project deploy start` from inside that directory | | `sf agent generate agent-spec` / publish fails on licensing or "default agent user" | Agentforce toggle is off or no Agentforce Service Agent User license is available. Enable it or free/provision a license (`references/agentforce-prerequisite.md`) | | Using a `Flow` Id (`301…`) as `SessionHandlerId` | Wrong handle — `SessionHandlerId` needs the stable `FlowDefinition` Id (`300…`); `resolve-flow-definition.sh` returns it | | Inbound flow deployed but the channel won't route to the agent | The agent must be **activated**, not just published, and the inbound flow must have an active version — `create-voice-agent.sh` verifies `BotVersion` is `Active`; `resolve-flow-definition.sh` exits 3 if there is no active version | --- ## Output Expectations This skill primarily creates records in the target org: - A procured phone number (Number Management). - An active `PstnVoice` `MessagingChannel` — routed to the contact center queue (Omni Queue) or to an Agentforce agent via an inbound routing flow with the queue as fallback (Omni Flow). - **Omni Flow only**: a published, active Agentforce agent plus two `RoutingFlow` flows (inbound `Copilot` + escalation `QueueBased`). - A report written per `assets/report-template.md`, plus a final summary table (`references/setup_summary.md`). The Omni Flow path also scaffolds a throwaway SFDX project under `acc-voice-build/` (spec, authoring bundle, flow metadata) to run the deploy — local build artifacts, not skill output. --- ## Cross-Skill Integration The Omni Flow path wires inbound voice itself (agent → inbound `Copilot` flow → channel, plus an escalation flow), so it does **not** hand that wiring off to a separate channel-configuration skill. Deeper agent authoring beyond the voice service agent this skill generates (custom topics, actions, knowledge) is out of scope. --- ## Reference File Index | File | When to read | |------|-------------| | `references/number_management_api.md` | Steps 3–4 — Number Management endpoints, params, and status-code mapping | | `references/verification_and_errors.md` | Step 6 — live-verification polling strategy and error handling | | `references/messaging_channel.md` | Step 9 — MessagingChannel field contract (both routing models) and create-time error handling | | `references/omni-flow-routing.md` | Step 9 (Omni Flow) — routing-model contract, agent→flow→channel wiring order, new-vs-existing fork, planner deviation, fallback rule | | `references/agentforce-prerequisite.md` | Step 9 (Omni Flow) — Agentforce toggle prerequisite, preflight check, and Omni-Queue fallback | | `references/setup_summary.md` | Step 10 — user-facing summary table and next steps | | `assets/report-template.md` | Step 10 — exact structure for the written `report.md` | | `assets/omni-flow.flow-meta.xml` | Step 9 (Omni Flow) — inbound `Copilot` RoutingFlow template (rendered by `create-routing-flows.sh`) | | `assets/escalation-flow.flow-meta.xml` | Step 9 (Omni Flow) — escalation `QueueBased` RoutingFlow template (rendered by `create-routing-flows.sh`) | | `scripts/prepare-agent-workdir.sh` | Step 9 (Omni Flow) — prepare the SFDX project context required before generating an agent spec | | `scripts/fetch-numbers.sh` | Step 3 — fetch available default numbers | | `scripts/procure-number.sh` | Step 4 — procure the selected number | | `scripts/resolve-channel-line.sh` | Step 5 — resolve the CommunicationChannelLine with retry |