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:

   # 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.

1. 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

1. 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.

1. Deploy:

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

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.

1. Bind the bot via Data API PATCH:

   CHAN_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
   BOT_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
   QUEUE_ID=$(sf data query --target-org $ORG --json \
     --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")

   sf api request rest --method PATCH -o $ORG \
     "/services/data/v67.0/sobjects/MessagingChannel/${CHAN_ID}" \
     --body "{\"SessionHandlerId\":\"${BOT_ID}\",\"FallbackQueueId\":\"${QUEUE_ID}\"}"
   # Expected: HTTP 204

1. Verify:

   sf data query --target-org $ORG --json \
     --query "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id='${CHAN_ID}'"

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 republish; deploy sessionHandlerType + sessionHandlerQueue via metadata, then bind SessionHandlerId via Data API PATCH | sessionHandlerAsa is not accepted by the Metadata API at v67 — the deploy silently drops it, so bot binding must happen via the Data API PATCH after deploy. Bot must be Active before the PATCH |

| Branches B/C: always create a new RoutingFlow — never reuse existing org flows | OOB platform flows commonly have ActiveVersionId: null and cannot be referenced |

| Branches B/C: use routingType: Copilot and copilotLabel — not QueueBased | QueueBased routes to the queue directly; Copilot routes to the agent first with the queue as fallback |

| Queue Id must be queried and embedded in the RoutingFlow XML | The queueId parameter requires a hardcoded 18-char record Id — do not leave it empty |

| Queue naming: {ChannelTypeLabel} Queue | Named after the channel type, not the agent |

| Outbound escalation is optional — never block inbound routing completion on it | Inbound and outbound are independent; inbound wiring is complete without the outbound step |

| Branch C: deploy BotEmailDefinition via --metadata-dir, never --metadata BotEmailDefinition:<name> | Not in the CLI's SDR registry, so the named-type deploy fails; metadata-format works |

| Branch C: do not wire an agent carrying a ServiceCustomerVerification topic to email | Detect and stop — do not auto-remove (may be legitimate for a multi-surface agent). See channel-branch-email.md Step 4a |

---

Verification checklist

Queue

• [ ] Queue has a QueueSobject record with the correct SobjectType for the channel type
• [ ] Running user is a member of the queue (if newly created)
• [ ] Queue has a QueueRoutingConfig with the correct CapacityPercentage (50 / 100 / 25 for Chat / Voice / Email)

Branch A — MessagingChannel

• [ ] SessionHandlerType = AgentforceServiceAgent after deploy
• [ ] Bot is Active before the Data API PATCH
• [ ] SessionHandlerId is non-null after the Data API PATCH (matches the bot's BotDefinition.Id, starts with 0Xx)
• [ ] FallbackQueueId is non-null after the Data API PATCH (matches the resolved queue Id)

Branches B/C — RoutingFlow

• [ ] RoutingFlow ActiveVersionId is non-null
• [ ] routingType = Copilot in the flow's routeWork action
• [ ] copilotLabel matches the agent's exact MasterLabel
• [ ] queueId is populated (non-empty)

Branch C — Email routing address

• [ ] If new: EmailRoutingAddress record created with correct PersonalName and Address
• [ ] If new: CaseSettings patched with caseOrigin, saveEmailHeaders: true, addressType: EmailToCase
• [ ] If new: user informed that a verification email was sent to the support address (non-blocking)

Branch C — BotEmailDefinition

• [ ] Preflight passed: agent is EinsteinServiceAgent with a bot user holding agentforceServiceAgentUser; active version carries the ServiceEmail surface; no ServiceCustomerVerification topic on the email agent
• [ ] Reply EmailTemplate is SFX, HTML, public, and contains [[[GENERATED_CONTENT]]] + [[[LEGAL_DISCLOSURE]]]
• [ ] Headless path (API ≥68): BotEmailDefinition deployed via --metadata-dir with success: true; legalDisclaimer/signature ≥10 chars
• [ ] Routing address's botEmailDefinition child set to the deployed component fullName
• [ ] Inbound routing set on the same routing address: caseOwner+caseOwnerType or routingFlow+fallbackQueue, with casePriority present

Optional Phase 3 — Outbound escalation

• [ ] service-agentforce-human-escalation-configure returned CONFIGURED or ALREADY-CONFIGURED

---

Reference file index

| File | When to read |

|---|---|

| references/channel-types.md | Phase 1 — determine SobjectType and routing branch |

| references/queue-resolution.md | Phase 1 — queue lookup, creation, and Id capture |

| references/live-traffic-gate.md | Phase 2 — detection queries, deferred-flow rules, and manual wiring copy for the live-traffic warning gate |

| references/channel-branch-voice.md | Branch B — full Voice inbound wiring: PstnVoice channel selection, RoutingFlow, MessagingChannel assignment, modality voice: republish |

| references/channel-branch-email.md | Branch C — full Email-to-Case wiring: API v68.0+ precondition gate, CaseSettings flags, EmailRoutingAddress + read-modify-write patch, inbound RoutingFlow, mandatory connection service_email: surface block, headless BotEmailDefinition deploy, routing-address binding |

| references/botemaildefinition.md | Branch C Step 4 — BotEmailDefinition fields, save-time validation order, ASA template rules, --metadata-dir deploy recipe, ServiceEmail surface prerequisite, composite org gate |

| references/routing-flow.md | Branches B/C — inbound RoutingFlow XML template, deploy, verify |

| references/agent-wiring.md | Phase 3 (optional) — outbound escalation connection block |

| assets/BotEmailDefinition.botEmailDefinition-meta.xml | Branch C Step 4c — starting template for the BotEmailDefinition source file |

| assets/mdapi-package.xml | Branch C Step 4c — metadata-format package.xml for the --metadata-dir deploy |

| assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email + .email-meta.xml | Branch C Step 4b (fallback) — minimal ASA-compliant SFX reply template when the user has none |

| scripts/validate-botemaildefinition.py | Branch C Step 4c — validate the BotEmailDefinition file before deploy |

| scripts/validate-emailtemplate.py | Branch C Step 4b (fallback) — validate the SFX template before deploy |