@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-agentforce-channel-configure/SKILL.md

@@ -0,0 +1,271 @@
+---
+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. Applies to any already-created agent, including an existing Help Agent. The channel infrastructure (MessagingChannel, Voice config, email-to-case) must already exist — this skill only adds the 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 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.0"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "agentforce-generate"
+    - "service-digital-engagement-channel-configure"
+    - "service-digital-engagement-deployment-configure"
+    - "service-helpagent-coordinate"
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# 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): same inbound RoutingFlow, using the org-specific Case-based ServiceChannel
+- Optional outbound escalation: adding the appropriate `connection {type}:` block to the agent and republishing
+
+**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
+- Outbound escalation RoutingFlow creation — surface the gap if one is needed and doesn't exist
+
+---
+
+## 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 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`.
+
+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).
+
+All five steps below are mandatory and must run in order — do **not** skip the retrieve/edit/deploy and jump straight to the PATCH. Run the retrieve and edit in the **current working directory** (a real SFDX project), so the edited `.messagingChannel-meta.xml` is saved into the project's `force-app` tree — not a throwaway temp dir. Steps 1–3 record the routing change in source; steps 4–5 apply the binding the Metadata API can't.
+
+1. **Retrieve the current MessagingChannel metadata** into the working-directory project:
+   ```bash
+   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>`):
+   ```xml
+   <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:**
+   ```bash
+   sf project deploy start \
+     --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
+     --target-org $ORG
+   ```
+
+4. **Bind the bot via Data API PATCH:**
+   ```bash
+   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
+   ```
+
+5. **Verify:**
+   ```bash
+   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
+
+Wires a `PstnVoice` MessagingChannel to the agent via an inbound `Copilot`-type RoutingFlow with the queue as fallback. Distinct from Branch A: no `sessionHandlerAsa`; the channel is bound to the flow (`sessionHandlerType=Flow`), and the agent needs a `modality voice:` block appended before republish.
+
+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 (its `references/channel-voice.md`); 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
+
+Same inbound RoutingFlow shape as Branch B, but using the org-specific Case-based ServiceChannel. Additionally requires an outbound `connection service_email:` and a mandatory manual BotEmailDefinition step in Setup — these are not optional and cannot be deferred to Phase 3.
+
+Follow `references/channel-branch-email.md` end to end. Highlights:
+
+- Step 0 — verify `emailToCase.enableEmailToCase` and `emailToCase.enableOnDemandEmailToCase` are `true` in CaseSettings via the Tooling API; if either is off, deploy a settings file that enables both (safe-fields-only pattern) before continuing.
+- Step 1 — reuse an existing `EmailRoutingAddress` or create one for the support email address, then patch `caseOrigin` / `saveEmailHeaders: true` / `addressType: EmailToCase` for that entry in `CaseSettings.Metadata.caseEmailRoutingAddresses` via Tooling-API PATCH (fallback: `sf project deploy start --metadata Settings:Case`). Inform the user about the verification email but do not block on it.
+- Step 2 — query the Case-based ServiceChannel (see `references/channel-types.md`), then write and deploy the inbound RoutingFlow using the template in `references/routing-flow.md`; verify `ActiveVersionId` is non-null.
+- Step 3 — mandatory outbound: reuse or create `{AgentDevName}_Outbound_Email_Flow` (QueueBased template in `references/routing-flow.md` Part 2), then add `connection service_email:` to the agent and republish per `references/agent-wiring.md`.
+- Step 4 — mandatory manual: prompt the user to create an **Email Configuration for Agentforce Service Agent** at `{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home` and set the Agentforce Configuration field on the Email-to-Case routing address. Wait for user confirmation.
+
+Branch C is complete once the user confirms Step 4. Skip Phase 3 for Email-to-Case (outbound escalation is already handled inline).
+
+---
+
+### Phase 3 — Outbound escalation (optional — Branches A/B only)
+
+> **Branch C (Email-to-Case):** outbound escalation was handled inline in Branch C above. Do not run Phase 3 for Email-to-Case.
+
+After inbound routing is confirmed (Branches A or B), 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:
+
+1. **Resolve the escalation queue** — follow the escalation queue resolution steps in `references/queue-resolution.md` (Step 6). The user may want a different queue for escalation than the inbound fallback. Capture `ESCALATION_QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID`.
+
+2. **Determine the outbound flow name** from the channel type (see naming table in `references/routing-flow.md` Part 2).
+
+3. **Check if an active outbound flow already exists:**
+   ```bash
+   sf data query --target-org $ORG --json \
+     --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{OUTBOUND_FLOW_DEVELOPER_NAME}' AND ProcessType='RoutingFlow'"
+   ```
+   - Row exists with non-null `ActiveVersionId` → reuse it; skip to step 4.
+   - Row missing or `ActiveVersionId` null → create the flow using the QueueBased template in `references/routing-flow.md` Part 2, substituting `ESCALATION_QUEUE_DEVELOPER_NAME` for `QUEUE_DEVELOPER_NAME`. Deploy and verify `ActiveVersionId` is non-null before continuing.
+
+4. **Add the connection block** to the agent's `.agent` file and republish — follow `references/agent-wiring.md`. The connection key depends on channel type:
+   - **Enhanced Chat (EmbeddedMessaging)** → `connection customer_web_client:`
+   - **Enhanced Messaging (3rd-party)** → `connection messaging:`
+   - **Voice** → `connection telephony:`
+   - **Email-to-Case** → `connection service_email:`
+
+---
+
+## 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 for Branches A/B — mandatory for Branch C (Email-to-Case) | BotEmailDefinition (Email Configuration in Setup) requires `connection service_email:` to already be on the agent; it cannot be created before the connection block is deployed |
+
+---
+
+## 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
+- [ ] User has confirmed creation of Email Configuration for Agentforce Service Agent at `/lightning/setup/AsaForEmail/home`
+- [ ] Email-to-Case routing address has the Agentforce Configuration field set
+
+### Optional Phase 3 — Outbound escalation
+- [ ] Correct connection block used: `customer_web_client:` for EmbeddedMessaging, `messaging:` for 3rd-party, `telephony:` for Voice, `service_email:` for Email-to-Case
+- [ ] `outboundRouteName` and `outboundRouteType` present in the correct `<plannerSurfaces>` entry of the deployed bundle
+- [ ] Agent status is Active after republish
+
+---
+
+## 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: CaseSettings flags, EmailRoutingAddress + read-modify-write patch, inbound RoutingFlow, mandatory outbound `connection service_email:`, BotEmailDefinition manual step |
+| `references/routing-flow.md` | Branches B/C — inbound RoutingFlow XML template, deploy, verify |
+| `references/agent-wiring.md` | Phase 3 (optional) — outbound escalation `connection messaging:` block |

package/skills/service-agentforce-channel-configure/references/agent-wiring.md

@@ -0,0 +1,97 @@
+# Agent wiring — outbound escalation (optional)
+
+This step is optional and presented to the user after inbound routing is complete. It configures the agent to hand off to a human agent via outbound escalation.
+
+> **Scope note:** This is distinct from inbound routing (which routes incoming work items *to* the agent). Outbound escalation adds a `connection {type}:` block to the agent's `.agent` YAML so the agent can transfer a conversation *to a queue* when the customer requests a human. The outbound routing flow used here is a different flow from the inbound one created in Phase 2.
+
+## Connection block by channel type
+
+The connection block name depends on the channel type being wired:
+
+| Channel type | Connection block | `outbound_route_type` |
+|---|---|---|
+| Enhanced Chat (EmbeddedMessaging) | `connection customer_web_client:` | `OmniChannelFlow` |
+| Enhanced Messaging (3rd-party) | `connection messaging:` | `OmniChannelFlow` |
+| Voice | `connection telephony:` | `OmniChannelFlow` |
+
+## Prerequisite
+
+An outbound RoutingFlow (`routingType: QueueBased`, routes to the fallback queue) must already exist. If one doesn't exist, create it using the QueueBased template in `references/routing-flow.md` Part 2 before proceeding here.
+
+Verify the outbound flow exists:
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ProcessType='RoutingFlow' AND ApiName='{OUTBOUND_FLOW_DEVELOPER_NAME}'"
+```
+`ActiveVersionId` must be non-null.
+
+## Add the connection block to the agent
+
+Retrieve the agent's authoring bundle:
+```bash
+sf project retrieve start \
+  --metadata "GenAiPlannerBundle:{AGENT_DEVELOPER_NAME}" \
+  --target-org $ORG
+```
+
+Add the appropriate block to the agent's `.agent` YAML. For **Enhanced Chat** (`connection customer_web_client:`):
+
+```yaml
+connection customer_web_client:
+    outbound_route_type: "OmniChannelFlow"
+    outbound_route_name: "flow://{OUTBOUND_FLOW_DEVELOPER_NAME}"
+    escalation_message: "Transferring you to a live agent — please hold on a moment."
+    adaptive_response_allowed: True
+```
+
+For **Enhanced Messaging** (`connection messaging:`):
+
+```yaml
+connection messaging:
+    outbound_route_type: "OmniChannelFlow"
+    outbound_route_name: "flow://{OUTBOUND_FLOW_DEVELOPER_NAME}"
+    escalation_message: "Transferring you to a live agent — please hold on a moment."
+    adaptive_response_allowed: True
+```
+
+For **Voice** (`connection telephony:` + `modality voice:`):
+
+Voice requires two blocks. Add both if they are not already present:
+
+```yaml
+modality voice:
+    voice_id: "UgBBYS2sOqTuMpoF3BR0"
+    outbound_speed: 1.0
+    outbound_stability: 0.65
+    outbound_similarity: 0.75
+
+connection telephony:
+    outbound_route_type: "OmniChannelFlow"
+    outbound_route_name: "flow://{OUTBOUND_FLOW_DEVELOPER_NAME}"
+    escalation_message: "Finding an associate for you..."
+    adaptive_response_allowed: True
+```
+
+If a block for the relevant connection type already exists in the file, **add the outbound fields to the existing block** rather than creating a duplicate. Do not overwrite fields that are already present. If `modality voice:` already exists, leave it as-is — do not overwrite existing voice tuning values.
+
+## Republish and activate the agent
+
+```bash
+sf agent validate authoring-bundle --api-name {AGENT_DEVELOPER_NAME} --json
+sf agent publish  authoring-bundle --api-name {AGENT_DEVELOPER_NAME} --json
+echo "Y" | sf agent activate       --api-name {AGENT_DEVELOPER_NAME} --json
+```
+
+## Verify the wiring round-tripped
+
+After publish, retrieve the bundle and check:
+```bash
+grep -n "outboundRouteName\|outboundRouteType" \
+  force-app/main/default/genAiPlannerBundles/{AGENT_DEVELOPER_NAME}_v*/\*.genAiPlannerBundle
+```
+
+Both `outboundRouteName` and `outboundRouteType` must be present in the correct `<plannerSurfaces>` entry. The compiled XML maps the connection blocks as:
+- `connection customer_web_client:` → `<surfaceType>CustomerWebClient</surfaceType>`
+- `connection messaging:` → `<surfaceType>Messaging</surfaceType>`
+
+If absent, the connection block was not serialised correctly — re-retrieve the `.agent` file and confirm the YAML was written before publishing.

package/skills/service-agentforce-channel-configure/references/channel-branch-email.md

@@ -0,0 +1,145 @@
+# Branch C — Email-to-Case inbound routing
+
+Same inbound RoutingFlow shape as Branch B, but using the org-specific Case-based ServiceChannel. Also includes the mandatory outbound `connection service_email:` and a mandatory manual BotEmailDefinition step (Email Configuration in Setup).
+
+## Step 0 — Enable Email-to-Case
+
+Ensure the two required CaseSettings flags are on. Read the current state:
+
+```bash
+sf api request rest -o "$ORG" --method GET \
+  "/services/data/v67.0/tooling/query?q=SELECT+Metadata+FROM+CaseSettings+LIMIT+1"
+```
+
+Check `metadata.emailToCase.enableEmailToCase` and `metadata.emailToCase.enableOnDemandEmailToCase`. If either is `false`, deploy a settings file that sets both to `true` (use the same safe-fields-only Metadata API deploy pattern used when patching routing addresses — include only the `emailToCase` block with known-safe fields). Verify they are `true` before continuing.
+
+---
+
+## Step 1 — Existing routing address or new one?
+
+Query existing Email-to-Case routing addresses on the org:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, PersonalName, Address FROM EmailRoutingAddress ORDER BY PersonalName"
+```
+
+Ask the user via `AskUserQuestion`:
+- **One or more found** → present each as `{PersonalName} <{Address}>`, plus *"Create a new email routing address"*
+- **Zero found** → skip the question; proceed directly to create a new routing address
+
+### If creating a new routing address
+
+1. Ask for the support email address:
+
+   > *"What email address should receive support emails? This is the address customers will email — e.g. `support@yourcompany.com`.*
+   > *Note: Salesforce will send a verification email to this address. You must click the verification link before inbound emails will be processed."*
+
+2. Create the `EmailRoutingAddress` record:
+   ```bash
+   sf data create record --target-org $ORG \
+     --sobject EmailRoutingAddress \
+     --values "PersonalName='{SUPPORT_EMAIL}' Address='{SUPPORT_EMAIL}'" \
+     --json
+   ```
+   Capture the new record `Id` as `ROUTING_ADDRESS_ID`.
+
+3. Set `CaseOrigin`, `SaveEmailHeaders`, and `AddressType` via CaseSettings read-modify-write:
+
+   a. Read current CaseSettings from the Tooling API:
+   ```bash
+   sf api request rest -o "$ORG" --method GET \
+     "/services/data/v67.0/tooling/query?q=SELECT+Metadata+FROM+CaseSettings+LIMIT+1"
+   ```
+
+   b. In the returned `Metadata.caseEmailRoutingAddresses` array, find the entry whose `emailAddress` matches `{SUPPORT_EMAIL}`. Patch that entry:
+   - `caseOrigin`: query `Case.Origin` picklist values and select `Email` if present, otherwise the closest match
+   - `saveEmailHeaders`: `true`
+   - `addressType`: `EmailToCase`
+
+   c. Deploy the patched Metadata back:
+   ```bash
+   sf api request rest -o "$ORG" --method PATCH \
+     "/services/data/v67.0/tooling/sobjects/CaseSettings/{CASE_SETTINGS_ID}" \
+     --body '{"Metadata": {<patched metadata object>}}'
+   ```
+   Run this from `/tmp/sfskills` (a valid SFDX project directory). If the Tooling API PATCH fails, fall back to Metadata API deploy via `sf project deploy start --metadata Settings:Case`.
+
+4. Inform the user about email verification — then continue without waiting:
+
+   > *"A verification email has been sent to `{SUPPORT_EMAIL}`. Click the link in that email when you get it — inbound mail won't be processed until the address is verified, but you can complete the rest of the setup now.*
+   >
+   > *If you don't receive the verification email, your domain may have email verification policies that block it:*
+   > *[Email Verification Requirements for Salesforce Orgs](https://help.salesforce.com/s/articleView?id=xcloud.security_email_verification_requirements.htm&type=5)*"*
+
+   Continue to the next step immediately — do not wait for the user to confirm.
+
+### If using an existing routing address
+
+Set `ROUTING_ADDRESS_ID` to the selected record's `Id` and continue. No provisioning steps needed.
+
+---
+
+## Step 2 — Inbound RoutingFlow
+
+1. **Query the ServiceChannel** — see `channel-types.md`. Stop if zero rows; ask user if multiple rows.
+
+2. **Determine names:**
+   - Flow label: `{AgentLabel} Inbound Email Flow`
+   - DeveloperName: `{AgentDevName}_Inbound_Email_Flow`
+   - `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL` from the queried ServiceChannel
+
+3. **Write the RoutingFlow XML** to `force-app/main/default/flows/{AgentDevName}_Inbound_Email_Flow.flow-meta.xml` using the template in `routing-flow.md`. Substitute all tokens including `{QUEUE_ID}` from Phase 1.
+
+4. **Deploy and verify `ActiveVersionId` is non-null** (see `routing-flow.md`).
+
+No agent file changes from inbound routing.
+
+---
+
+## Step 3 — Mandatory outbound escalation: `connection service_email:`
+
+Unlike other channel types where outbound escalation is optional, Email-to-Case requires the `connection service_email:` block to be on the agent before the BotEmailDefinition (Email Configuration) can be created in Setup — the Setup UI requires the agent to already have this connection wired.
+
+Do not offer this as optional or skip to Phase 3. Run these steps now:
+
+1. **Determine the outbound flow name:**
+   - Flow label: `{AgentLabel} Outbound Email Flow`
+   - DeveloperName: `{AgentDevName}_Outbound_Email_Flow`
+
+2. **Check if an active outbound flow already exists:**
+   ```bash
+   sf data query --target-org $ORG --json \
+     --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{AgentDevName}_Outbound_Email_Flow' AND ProcessType='RoutingFlow'"
+   ```
+   - Row exists with non-null `ActiveVersionId` → reuse it; skip to step 3.
+   - Row missing or `ActiveVersionId` null → create using the QueueBased template in `routing-flow.md` Part 2, with the `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL` queried above and `QUEUE_DEVELOPER_NAME` from Phase 1. Deploy and verify `ActiveVersionId` is non-null.
+
+3. **Add `connection service_email:` to the agent and republish** — follow `agent-wiring.md`. Verify the connection block is present in the deployed bundle before continuing.
+
+---
+
+## Step 4 — Mandatory manual step: BotEmailDefinition (cannot be automated)
+
+The `BotEmailDefinition` metadata type is not yet deployable via `sf project deploy`. Surface this step only after the outbound connection block is confirmed deployed:
+
+> *"The inbound routing flow and outbound escalation are now configured. One final manual step is required: you must create an **Email Configuration for Agentforce Service Agent** in Setup.*
+>
+> *Go to: `{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home` → New*
+>
+> *Fill in the following fields:*
+> - *Label / DeveloperName: use the agent name for identification, e.g. `{AgentLabel} Email Configuration`*
+> - *Agent: select **{AgentLabel}***
+> - *Reply Template: an email template containing `[[[GENERATED_CONTENT]]]` (the agent's reply body) and `[[[LEGAL_DISCLOSURE]]]` (required legal footer placeholder)*
+> - *Legal Disclaimer: the legal text shown at the bottom of every agent reply email (required)*
+> - *Signature: the agent's sign-off text, e.g. agent name and title (required)*
+>
+> *If you don't have suitable email templates yet, open the App Launcher and search for **Email Templates** to create them. The reply template must include `[[[GENERATED_CONTENT]]]` and `[[[LEGAL_DISCLOSURE]]]` as literal placeholder strings.*
+>
+> *Once the Email Configuration is saved, open your Email-to-Case configuration (Setup → Feature Settings → Service → Email-to-Case → edit the relevant routing address) and set the **Agentforce Configuration** field to the configuration you just created.*
+>
+> *Reference: [Email Configurations for Agentforce Service Agent](https://help.salesforce.com/s/articleView?id=ai.service_agent_email_configuration.htm&type=5)*
+>
+> Please confirm when this setup step is complete."*
+
+Branch C is complete once the user confirms. Phase 3 outbound escalation has already been handled above — skip Phase 3 for Email-to-Case.

package/skills/service-agentforce-channel-configure/references/channel-branch-voice.md

@@ -0,0 +1,69 @@
+# Branch B — Voice inbound routing
+
+Wires an Agentforce agent to a `PstnVoice` MessagingChannel via an inbound RoutingFlow. The queue resolved in Phase 1 acts as the fallback when the agent is unavailable.
+
+## Step 0 — Existing channel or new number?
+
+Query for existing `PstnVoice` MessagingChannels on the org:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT DeveloperName, MasterLabel, MessagingPlatformKey FROM MessagingChannel WHERE MessageType='PstnVoice' AND IsActive=true"
+```
+
+Ask the user via `AskUserQuestion`:
+- **One or more found** → present each as an option (`{MasterLabel} — {MessagingPlatformKey}`), plus *"Provision a new phone number"*
+- **Zero found** → skip the question; proceed directly to provision a new number
+
+**If provisioning a new number:** phone number provisioning is handled upstream by `service-helpagent-coordinate` (its own `channel-voice.md` reference) before this skill is invoked. By the time Branch B runs, the `PstnVoice` MessagingChannel already exists — set `CHANNEL_DEVELOPER_NAME` to its `DeveloperName` and proceed.
+
+**If using an existing channel:** set `CHANNEL_DEVELOPER_NAME` to the selected channel's `DeveloperName`.
+
+> **Check native vs 3rd-party telephony before creating the RoutingFlow.** See `channel-types.md` — if the org uses a partner telephony provider, stop and surface the message there. Do not proceed with RoutingFlow creation.
+
+## Step 1 — Determine names
+
+- Flow label: `{AgentLabel} Inbound Voice Flow`
+- DeveloperName: `{AgentDevName}_Inbound_Voice_Flow`
+- `SERVICE_CHANNEL_DEV_NAME`: `sfdc_phone`
+- `SERVICE_CHANNEL_LABEL`: `Phone`
+
+## Step 2 — Write the RoutingFlow XML
+
+Write to `force-app/main/default/flows/{FLOW_DEVELOPER_NAME}.flow-meta.xml` using the template in `routing-flow.md`. Substitute all tokens including `{QUEUE_ID}` from Phase 1.
+
+## Step 3 — Deploy and verify
+
+Deploy and verify `ActiveVersionId` is non-null (see `routing-flow.md`).
+
+## Step 4 — Assign the flow to the MessagingChannel
+
+Deploy a `MessagingChannel` metadata file for `{CHANNEL_DEVELOPER_NAME}` with `sessionHandlerType=Flow`, `sessionHandlerFlow={FLOW_DEVELOPER_NAME}`, and `sessionHandlerQueue={QUEUE_DEVELOPER_NAME}`. This sets the "Flow Definition" field in Setup — without this step the flow is deployed but never executed and calls hang up immediately.
+
+```xml
+<MessagingChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>{CHANNEL_LABEL}</masterLabel>
+    <messagingChannelType>PstnVoice</messagingChannelType>
+    <sessionHandlerFlow>{FLOW_DEVELOPER_NAME}</sessionHandlerFlow>
+    <sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>
+    <sessionHandlerType>Flow</sessionHandlerType>
+</MessagingChannel>
+```
+
+Verify: query `MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'` and confirm `SessionHandlerId` starts with `300` (FlowDefinition prefix).
+
+## Step 5 — Add `modality voice:` to the agent and republish
+
+Retrieve the agent's authoring bundle, then add the following block at the end of the `.agent` file if it is not already present:
+
+```yaml
+modality voice:
+    voice_id: "UgBBYS2sOqTuMpoF3BR0"
+    outbound_speed: 1.0
+    outbound_stability: 0.65
+    outbound_similarity: 0.75
+```
+
+Do not ask the user for a `voice_id` — always use the platform default above ("Mark", en_US). The user can customize the voice afterward in Agent Builder → Connections → Voice. Then validate, publish, and activate the agent per `agent-wiring.md`. Verify the block round-tripped by re-retrieving the bundle.
+
+Proceed to Phase 3 (optional).

package/skills/service-agentforce-channel-configure/references/channel-types.md

@@ -0,0 +1,61 @@
+# Channel types reference
+
+## Channel type matrix
+
+| Channel type | SobjectType (queue) | Routing branch | SERVICE_CHANNEL_DEV_NAME | SERVICE_CHANNEL_LABEL |
+|---|---|---|---|---|
+| Enhanced Chat | `MessagingSession` | Branch A — set `sessionHandlerAsa` on MessagingChannel | `sfdc_livemessage` | `Messaging` |
+| Enhanced Messaging (3rd-party: WhatsApp, SMS, etc.) | `MessagingSession` | Branch A — set `sessionHandlerAsa` on MessagingChannel | `sfdc_livemessage` | `Messaging` |
+| Voice | `VoiceCall` | Branch B — create inbound RoutingFlow (`routingType: Copilot`) | `sfdc_phone` | `Phone` |
+| Email-to-Case | `Case` | Branch C — create inbound RoutingFlow (`routingType: Copilot`) | *(query required — see below)* | *(query required)* |
+
+## Email-to-Case: query the org-specific ServiceChannel
+
+The Case-based ServiceChannel DeveloperName and Label are not system-generated and vary by org. Query before writing the RoutingFlow:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT DeveloperName, MasterLabel FROM ServiceChannel WHERE RelatedEntityType='Case'"
+```
+
+- **Zero rows** → stop; surface gap to user. The channel cannot be wired until a Case-based ServiceChannel exists.
+- **One row** → use its `DeveloperName` as `SERVICE_CHANNEL_DEV_NAME` and `MasterLabel` as `SERVICE_CHANNEL_LABEL`.
+- **Multiple rows** → ask user to choose via `AskUserQuestion`.
+
+## Voice: native vs partner — MUST CHECK before Branch B
+
+Branch B only works with **native Service Cloud Voice**. Partner telephony providers (Amazon Connect, Genesys, Avaya, etc.) manage their own routing pipelines and do not honour Salesforce RoutingFlows — wiring the agent via `routingType: Copilot` on a partner channel will have no effect.
+
+**Detection method: query `CommunicationChannelLine` via the Tooling API.**
+
+`CommunicationChannelLine` is a Tooling API object (not SOQL-queryable). Native SCV phone numbers have a `CommunicationChannelLine` record whose `DeveloperName` follows the pattern `DEV_{digits}` (e.g. `DEV_13375909051`). Partner voice channels do not.
+
+**Step 1 — Extract the digits from the MessagingChannel DeveloperName.**
+
+`PstnVoice` channels follow the pattern `VOICE_PSTN_{digits}` (e.g. `VOICE_PSTN_13375909051`). Strip the `VOICE_PSTN_` prefix to get the digits (e.g. `13375909051`).
+
+**Step 2 — Query `CommunicationChannelLine` via the Tooling API:**
+
+```bash
+sf data query --target-org $ORG --json --use-tooling-api \
+  --query "SELECT Id, DeveloperName FROM CommunicationChannelLine WHERE DeveloperName='DEV_{DIGITS}' LIMIT 1"
+```
+
+Interpret results:
+
+| Result | Verdict |
+|---|---|
+| Query returns 1+ row | **Native SCV** — Branch B is supported |
+| Query returns 0 rows | **Partner voice** — Branch B not supported |
+
+**If partner voice:** stop and surface this to the user:
+
+> *"This voice channel uses a partner telephony provider. Routing to an Agentforce agent via a Salesforce RoutingFlow is not supported — routing is managed by the partner's system. Contact your telephony provider for agent routing options."*
+
+Do not proceed with RoutingFlow creation for partner voice channels.
+
+## Routing branch summary
+
+- **Branch A (messaging channels)**: No RoutingFlow. Set `sessionHandlerAsa` + `sessionHandlerQueue` directly on the existing `MessagingChannel` metadata. No agent republish.
+- **Branch B (Voice, native only)**: Detect native vs 3rd-party first (see above). If native, create an inbound RoutingFlow with `routingType: Copilot` pointing to the agent by label, with the queue as fallback. No agent file changes.
+- **Branch C (Email-to-Case)**: Same inbound RoutingFlow shape as Branch B, but with the org-specific Case-based ServiceChannel. No agent file changes.