Skip to content

forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-agentforce-human-escalation-configure

service-agentforce-human-escalation-configure

Unverified

Use to configure and verify Agentforce agent-to-human escalation, including human handoff, a staffed fallback queue, and failure-threshold directives. Triggers: configure agent escalation, escalate to a human agent, agent handoff to a queue, configure a human escalation queue, set an Agentforce fallback handoff. Do not use to create an agent or configure inbound channel routing; use service-agentforce-channel-configure for inbound routing.

references/_vendored/queue-resolution.md

View on GitHub
# Queue resolution

Run this before any channel wiring. The fallback queue must exist and have the correct `QueueSobject` record for the channel type's SobjectType.

## Step 1 — Query existing compatible queues

Determine the SobjectType from the channel type (see `references/channel-types.md`), then query:

```bash
sf data query --target-org $ORG --json \
  --query "SELECT Queue.Name, Queue.DeveloperName, Queue.Id
           FROM QueueSobject
           WHERE SobjectType='{SOBJECT_TYPE}'"
```

## Step 2 — Present to user via AskUserQuestion

- **One or more found** → present each as an option: `{Queue.Name} ({Queue.DeveloperName})`, plus a final option *"Create a new queue"*. If the user picks an existing queue, capture its `Name`, `DeveloperName`, and `Id` as `QUEUE_NAME`, `QUEUE_DEVELOPER_NAME`, and `QUEUE_ID`, validate all three per [input-validation.md](input-validation.md), and skip queue creation. If one fails its grammar, don't use that queue; offer to create a new one.
- **Zero found** → inform the user no compatible queue exists; proceed directly to create one.

## Step 3 — Create a new queue (if needed)

**Naming:** `{ChannelTypeLabel} Queue` / DeveloperName `{Channel_Type_Label}_Queue`

Examples:
- Voice → `Voice Queue` / `Voice_Queue`
- Enhanced Chat → `Enhanced Chat Queue` / `Enhanced_Chat_Queue`
- Email → `Email Queue` / `Email_Queue`

### 1. Create the Group record
```bash
QUEUE_ID=$(sf data create record --target-org $ORG \
  --sobject Group \
  --values "Type='Queue' Name='{QUEUE_NAME}' DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
  --json | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")
```

### 2. Grant queue access to the correct SobjectType
```bash
sf data create record --target-org $ORG \
  --sobject QueueSobject \
  --values "QueueId='$QUEUE_ID' SobjectType='{SOBJECT_TYPE}'"
```

### 3. Add the running user as a queue member
```bash
ORG_USERNAME=$(sf org display --target-org $ORG --json \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['username'])")
UNAME_RE='^[A-Za-z0-9][A-Za-z0-9._@+-]*$'
[[ "$ORG_USERNAME" =~ $UNAME_RE ]] || { echo "Org username '$ORG_USERNAME' fails the ORG_USERNAME grammar. Stopping."; exit 1; }
RUNNING_USER_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM User WHERE Username='$ORG_USERNAME'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
sf data create record --target-org $ORG \
  --sobject GroupMember \
  --values "GroupId='$QUEUE_ID' UserOrGroupId='$RUNNING_USER_ID'"
```

## Step 4 — Resolve or create a Routing Configuration

The queue must have a `QueueRoutingConfig` so Omni-Channel knows how to handle capacity. `QueueRoutingConfig` has **no `QueueId` column** — the link is the reverse direction (the queue's `Group` record points at the config via `QueueRoutingConfigId`), so resolve an existing config through the `Group` record, not by filtering the config on a queue Id:

```bash
sf data query --target-org $ORG --json \
  --query "SELECT QueueRoutingConfigId FROM Group WHERE Id='{QUEUE_ID}'"
```

- **`QueueRoutingConfigId` is non-null** → the queue already has a routing config; use it as-is and skip creation.
- **`QueueRoutingConfigId` is null** → create one using the capacity percentage for the channel type, then link it to the queue:

| Channel type | `CapacityPercentage` |
|---|---|
| Enhanced Chat / Enhanced Messaging | `50` |
| Voice | `100` |
| Email-to-Case | `25` |

All use `RoutingModel: LeastActive`.

`QueueRoutingConfig` uses `MasterLabel` (there is **no `Name` field**), has **no `QueueId`**, and **requires `RoutingPriority`** — a non-nillable integer with no default; set `1`. Create the config standalone, capture its Id, then point the queue's `Group` record at it:

```bash
QRC_ID=$(sf data create record --target-org $ORG \
  --sobject QueueRoutingConfig \
  --values "MasterLabel='{QUEUE_NAME} Routing' DeveloperName='{QUEUE_DEVELOPER_NAME}_Routing' CapacityPercentage={CAPACITY_PERCENTAGE} RoutingModel='LeastActive' RoutingPriority=1 IsAttributeBased=false" \
  --json | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")

# Link is the REVERSE direction — the queue's Group record points at the config:
sf data update record --target-org $ORG \
  --sobject Group --record-id "{QUEUE_ID}" \
  --values "QueueRoutingConfigId='$QRC_ID'"
```

Verify the queue now references the config:
```bash
sf data query --target-org $ORG --json \
  --query "SELECT Id, QueueRoutingConfigId FROM Group WHERE Id='{QUEUE_ID}'"
```
`QueueRoutingConfigId` must be non-null.

## Step 5 — Capture for use in Phase 2

Store:
- `QUEUE_DEVELOPER_NAME` — used in the MessagingChannel XML (Branch A) or RoutingFlow `queueId` lookup (Branches B/C)
- `QUEUE_NAME` (the `Name` field, e.g. `Voice Queue`) — used as `queueLabel` in the RoutingFlow XML
- `QUEUE_ID` (18-char record Id) — used as `queueId` in the RoutingFlow XML

If an existing queue was chosen, query its Id if not already available:
```bash
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'])")
```

---

## Step 6 — Escalation queue resolution (Phase 3 only)

Run this step when the user opts into outbound escalation (Branches A/B). The escalation queue is the human queue that receives escalated conversations — it may be the same as the inbound fallback queue, or a different one.

### Check whether other compatible queues exist

Query for queues with the correct SobjectType, excluding the inbound fallback queue already selected:

```bash
sf data query --target-org $ORG --json \
  --query "SELECT Queue.Name, Queue.DeveloperName, Queue.Id
           FROM QueueSobject
           WHERE SobjectType='{SOBJECT_TYPE}'
           AND Queue.DeveloperName != '{QUEUE_DEVELOPER_NAME}'"
```

### Branch on results

**Zero other queues exist** → no choice to offer; reuse the inbound fallback queue. Set `ESCALATION_QUEUE_DEVELOPER_NAME = QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID = QUEUE_ID`. Continue without asking.

**One or more other queues exist** → ask the user via `AskUserQuestion`:

> *"Which queue should receive escalated conversations from the agent?"*
> - *Use the same queue as inbound fallback: `{QUEUE_NAME}` ({QUEUE_DEVELOPER_NAME})* **(Recommended)**
> - *{OtherQueue.Name} ({OtherQueue.DeveloperName})* — one option per additional compatible queue

If the user picks the fallback: `ESCALATION_QUEUE_DEVELOPER_NAME = QUEUE_DEVELOPER_NAME`, `ESCALATION_QUEUE_ID = QUEUE_ID`.

If the user picks a different queue: capture its `DeveloperName` and `Id` as `ESCALATION_QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID`.

Use `ESCALATION_QUEUE_DEVELOPER_NAME` (not `QUEUE_DEVELOPER_NAME`) when writing the outbound RoutingFlow XML in Phase 3.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall