/service-agentforce-channel-configure

name: service-agentforce-channel-configure
description: "Wires an existing, active Agentforce agent to a channel by resolving a fallback queue, setting up inbound routing (either PATCH SessionHandlerId on the MessagingChannel, or an inbound RoutingFlow for Voice/Email), and optionally configuring outbound escalation. Use when the user wants to add a channel to an existing agent, connect an agent to a messaging or voice channel, route Voice or Email-to-Case to an Agentforce agent, or set up a fallback queue for an agent channel. Also applies to an existing Help Agent. The channel infrastructure must already exist — this skill adds routing. DO NOT TRIGGER when the agent does not yet exist or still needs Help Agent setup (use agentforce-generate or service-helpagent-coordinate), when setting up Email-to-Case with an agent end-to-end (use service-email-to-case-configure), when creating the MessagingChannel itself (use service-digital-engagement-channel-configure), or when creating an Embedded Service Deployment (use service-digital-engagement-deployment-configure)."
allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion
metadata:
  version: "1.1"
  domains: ["Service", "Agentforce"]
  minApiVersion: "67.0"
  relatedSkills:
    - "agentforce-generate"
    - "service-agentforce-human-escalation-configure"
    - "service-digital-engagement-channel-configure"
    - "service-digital-engagement-deployment-configure"
    - "service-email-to-case-configure"
    - "service-helpagent-coordinate"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck:
    - type: "license"
      value: "Agentforce"

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:**

   # 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