Service Agentforce Channel Configure

service-agentforce-channel-configure: Wire an Agentforce agent to a channel

Adds inbound routing between an existing channel and an existing Agentforce agent. The agent receives work items from the channel; a fallback queue handles overflow when the agent is unavailable.

This skill is generic — it works for any Agentforce agent, not just the Help Agent template.

Scope

In scope:

• Resolving or creating a fallback queue with the correct QueueSobject SobjectType
• Branch A (Enhanced Chat / Enhanced Messaging): deploying sessionHandlerType=AgentforceServiceAgent + sessionHandlerQueue on an existing MessagingChannel, then binding SessionHandlerId via Data API PATCH
• Branch B (Voice): assumes the phone number and PstnVoice MessagingChannel already exist (provisioned by the caller, e.g. service-helpagent-coordinate), then creating an inbound RoutingFlow (routingType: Copilot) that routes to the agent with the queue as fallback
• Branch C (Email-to-Case): inbound routing via direct case-owner assignment or an Omni-Channel RoutingFlow, plus deploying a BotEmailDefinition (Email Configuration) that links the agent to Service Email and binding it to the routing address
• Optional outbound escalation: delegating the verified agent-to-human handoff contract to service-agentforce-human-escalation-configure

Out of scope:

• Creating the agent — use agentforce-generate or service-helpagent-coordinate
• Creating the MessagingChannel — use service-digital-engagement-channel-configure
• Creating the Embedded Service Deployment — use service-digital-engagement-deployment-configure
• Creating the Voice or Email-to-Case channel infrastructure

Required inputs

• Agent `DeveloperName` and agent label (MasterLabel) — must be an existing, active agent
• Channel type — one of: Enhanced Chat, Enhanced Messaging (3rd-party), Voice, Email-to-Case
• Channel identifier — MessagingChannel DeveloperName (Branch A), or the channel name/context (Branches B/C)
• Target org alias

Workflow

Steps are sequential. Read references/channel-types.md first to confirm the routing branch before proceeding.

Phase 0 — Production write-guard (mandatory, before any write)

This skill performs metadata/data writes (MessagingChannel edits, RoutingFlow deploys, agent republish). Before any write, classify the target org and refuse real production:

sf data query --target-org $ORG --json \
  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1"

• safe_to_write is true only when IsSandbox=true, OR TrialExpirationDate is non-null (trial/CDO), OR OrganizationType is Developer Edition / Base Edition.
• If safe_to_write is false, stop — state plainly that this is a real production customer org and escalation/channel wiring will not be applied. Do not proceed to any write phase.
• If safe_to_write is true, show the write plan (which MessagingChannel/RoutingFlow/agent will change) and get explicit user confirmation of the target org before continuing.

Never bypass this gate — a mistaken production write here reroutes live customer traffic.

Phase 1 — Verify agent and resolve queue

1. Confirm the agent exists and has an active version: ```bash # Get the definition sf data query --target-org $ORG --json \ --query "SELECT Id, DeveloperName, MasterLabel FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"

# Check for an Active version sf data query --target-org $ORG --json \ --query "SELECT Id, Status FROM BotVersion WHERE BotDefinitionId='{BOT_DEFINITION_ID}' AND Status='Active' LIMIT 1"

   Stop with a clear message if the definition is not found or no version has `Status = Active`.

   > **Branch A caveat — an Active BotVersion is necessary but NOT sufficient to bind as `sessionHandlerAsa`.** The platform only accepts an agent that is provisioned/connected as a *deployable Agentforce Service Agent* (typically an `ExternalCopilot`). Binding an agent that is merely Active fails the Phase 2 deploy with `Only active Agentforce Service Agents are supported for a Messaging Channel`. Confirm bindability read-only before writing: if any MessagingChannel on the org already uses `sessionHandlerType=AgentforceServiceAgent`, retrieve it (`sf project retrieve start --metadata "MessagingChannel:{EXISTING}" --target-org $ORG`) and read its `<sessionHandlerAsa>` — that set is the org's provably-bindable ASAs. If the chosen agent is not a provisioned ASA and no bindable ASA exists, stop and report `BLOCKED`: *provide an agent that is provisioned as an Agentforce Service Agent.*

2. **Resolve the fallback queue and routing configuration** — follow `references/queue-resolution.md`:
   - Determine SobjectType from the channel type (see `references/channel-types.md`)
   - Query existing compatible queues; present via `AskUserQuestion` or create new
   - Query for an existing `QueueRoutingConfig`; create one with the correct capacity percentage if absent
   - Capture `QUEUE_DEVELOPER_NAME`, `QUEUE_NAME`, and `QUEUE_ID`

---

### Phase 2 — Wire inbound routing

#### Live-traffic warning gate (runs before any branch)

Before making any routing change, detect whether the channel already has active inbound routing (Branch A: non-empty `SessionHandlerType`; Branches B/C: any active RoutingFlow assigned to the service channel). If it does, first check whether the user's prompt already answered the timing choice ("do not cut over" / "wire manually" / "review first" → defer silently; "cut over now" / "activate immediately" → proceed silently). Only if the prompt is silent, warn via `AskUserQuestion` and let the user choose **"Re-route now"** or **"Set up, then wire manually"** — and on any ambiguous or no-selection response, default to the deferred path (never to a live re-route). When deferred, set `DEFER_INBOUND_ROUTING=true`, skip the channel-activation step in the chosen branch, and print the manual wiring instructions at the end of Phase 2.

If the channel has no existing routing, skip this gate entirely and proceed directly.

Full detection queries, exact `AskUserQuestion` block, deferred-flow rules per branch, and manual-wiring copy: `references/live-traffic-gate.md`.

---

#### Branch A — Enhanced Chat / Enhanced Messaging (3rd-party)

No RoutingFlow required. Deploy the MessagingChannel with `sessionHandlerType` + `sessionHandlerQueue` only, then bind the bot via a Data API PATCH. `sessionHandlerAsa` is not accepted by the Metadata API at v67 — the deploy silently drops it and `SessionHandlerId` stays null unless you run the PATCH. The bot must be Active before the PATCH ("Only active Agentforce Service Agents are supported" otherwise).

Run all five steps in order. Perform retrieve and edit in the **current SFDX project**, so the deploy reads the edited `.messagingChannel-meta.xml` from `force-app`; do not use a temporary directory.

1. **Retrieve the current MessagingChannel metadata** into the working-directory project:

sf project retrieve start \ --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \ --target-org $ORG

2. **Edit the retrieved `.messagingChannel-meta.xml` in place** — set exactly these two fields (do NOT add `<sessionHandlerAsa>`):

<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType> <sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>

   Apply this edit with the file-editing tool (Edit/Write) so the change is saved to the retrieved file at `force-app/main/default/messagingChannels/{CHANNEL_DEVELOPER_NAME}.messagingChannel-meta.xml` in the working directory — do **not** hand-edit it through an inline `sed`/`cat` heredoc into a temp path. The deploy in step 3 must read this same on-disk file.

3. **Deploy:**

sf project deploy start \