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 chann

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: 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: 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: 2. Edit the retrieved .messagingChannel meta.xml in place — set exactly these two fields (do NOT add <sessionHandlerAsa ): 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: If the deploy fails with Only active Agentforce Service Agents are supported for a Messaging Channel , the agent is not a bindable ASA on this org (see the Phase 1 caveat). Do not retry with the same agent — the channel is left unchanged (the failed deploy is atomic). Report BLOCKED with the remediation: bind an agent already provisioned as an Agentforce Service Agent, or provision this one, then re run. 4. Bind the bot via Data API PATCH: 5. Verify: Both SessionHandlerId and FallbackQueueId must be non null. No agent file changes — no republish needed. Proceed to Phase 3 (optional). Branch B — Voice Wire the PstnVoice MessagingChannel through an inbound Copilot RoutingFlow, with the queue as fallback, and add the required modality voice: block before republishing the agent. Follow references/channel branch voice.md end to end. Highlights: Step 0 — reuse an existing PstnVoice MessagingChannel or have service helpagent coordinate provision one first using that skill's Voice channel reference; abort if the org uses a partner telephony provider (see references/channel types.md ). Steps 1–3 — write and deploy the inbound RoutingFlow using the template in references/routing flow.md , verifying ActiveVersionId is non null. Step 4 — deploy a MessagingChannel metadata file for {CHANNEL DEVELOPER NAME} with sessionHandlerType=Flow , sessionHandlerFlow={FLOW DEVELOPER NAME} , sessionHandlerQueue={QUEUE DEVELOPER NAME} . Without this the flow is never executed and calls hang up. Verify SessionHandlerId starts with 300 . Step 5 — append the platform default modality voice: block (voice id UgBBYS2sOqTuMpoF3BR0 , "Mark", en US) to the .agent file if missing; do not ask the user. Republish per references/agent wiring.md . Proceed to Phase 3 (optional). Branch C — Email to Case Let the user choose direct case owner assignment or an Omni Channel Copilot RoutingFlow. This branch requires API v68.0+, a connection service email: surface, and a BotEmailDefinition. Follow references/channel branch email.md end to end. Load bearing gotchas (full walkthrough in that file): Step 1 — bind routing address fields via Tooling API PATCH or a metadata dir Settings:Case deploy, never a source metadata Settings:Case deploy (it reads sourceApiVersion and mutates the user's project). Step 2 — choose inbound routing ( AskUserQuestion ): case owner ( caseOwner = the agent's bot user) or Omni Channel flow ( Copilot RoutingFlow + routingFlow / fallbackQueue ). Resolve the bot user either way; routing fields go in the Step 4d deploy. Step 3 — the agent is already active, so add the mandatory connection service email: surface via deactivate → publish → activate (a plain publish fails with couldn't find the default agent user ). Batch the outbound route here too if escalation is wanted. Step 4 — BotEmailDefinition: preflight the save time gates, validate the reply template, deploy via metadata dir , then bind the routing address in one Settings:Case deploy ( botEmailDefinition + Step 2 routing fields + the required casePriority ). Stop on failure. Branch C is complete once the routing address binding is verified. Proceed to Phase 3. Phase 3 — Outbound escalation (optional) Authoritative owner: full agent to human escalation is owned by service agentforce human escalation configure . This includes the escalation topic, planner coupling, staffed human queue, outbound flow, failure threshold directives, republish, and deterministic verification. After inbound routing is confirmed, ask the user: "Inbound routing is now set up — the channel will route to [agent name]. Do you also want to configure outbound escalation so the agent can hand off to a human when requested?" If yes, delegate to service agentforce human escalation configure . Pass the resolved agent, channel type, context object, and fallback queue as known inputs. Do not duplicate that skill's write or verification steps here. Rules / constraints Rule Rationale Verify the agent exists and is Active before making any changes Wiring a channel to a non existent or inactive agent silently fails at runtime If the channel already has active inbound routing, honor an explicit defer/cutover intent in the prompt without asking; otherwise warn via AskUserQuestion and default to defer on ambiguity Re routing takes effect immediately and affects live traffic — queue and RoutingFlow creation always proceed; only the activation step is gated, and the safe default is non destructive When deferred, print exact manual wiring instructions before Phase 3 The operator needs to know precisely what to run when they're ready to cut over Never modify the MessagingChannel without retrieving the current metadata first Overwriting without retrieval discards existing settings Branch A: no RoutingFlow, no agent re

service-agentforce-channel-configure