Skip to content

forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-helpagent-coordinate

service-helpagent-coordinate

Flagged

Use to set up, configure, ground, or go live with a Salesforce Help Agent (an Agentforce Service Agent in Service Cloud) via a guided four-checkpoint flow. Use whenever a user says any of: set up / create / build / add a help agent, service agent, or support chat agent; add or embed a chat widget on a website or Experience Cloud / LWR site; put a help agent on a channel (web chat, voice, phone, help portal); ground a help agent on Salesforce Knowledge; or wants an AI to answer customer questions, manage support cases, and escalate to a human. The right skill even when the request names only one part or references help-agent-spec.md or the Agentforce Quick Setup wizard. DO NOT TRIGGER when authoring a brand-new agent with no Help Agent lineage (use agentforce-generate), configuring OAuth/ECAs (use integration-connectivity-connected-app-configure), or only deploying metadata (use platform-metadata-deploy).

FileKindSize
README.mdmarkdown5.8 KB
SKILL.mdskill md28.5 KB
assets/help-agent-spec.mdmarkdown41.8 KB
references/agent-script.mdmarkdown45.4 KB
references/channel-voice.mdmarkdown2.4 KB
references/channel-web-chat.mdmarkdown19.9 KB
references/output-report-format.mdmarkdown16.4 KB

references/channel-web-chat.md

View on GitHub
# Channel branch — Web Chat

> **When to read this file.** Load it only when the user has selected **Web Chat** at Checkpoint 3. If they selected Voice, read `channel-voice.md` instead. If they selected Help Portal, delegate to the sibling skill `service-concierge-portal-generate` — do not inline portal steps here. You do not need every channel file in context at once — read only the branch the user chose.

Web Chat embeds a chat widget on a website. This branch provisions a messaging channel + omni-channel routing, a new Embedded Service Deployment (`Help Chat`), and a prepared LWR Experience Cloud site. The agent script does **not** change here — this is channel/site metadata around the agent.

## Step A — Ask for the domain

Ask the user for **the domain** where the widget will live (e.g. `support.acme.com`). This is required — the embedded deployment ties the JavaScript snippet to that domain via a security key, so the snippet cannot be lifted onto an unauthorized site.

## Step B — CRITICAL, DO NOT SKIP: ask who will be chatting

**Step B checklist (do all three, in order):**
1. **Audience** — ask (or infer from the prompt) who will chat: `Public / anonymous`, `Both anonymous and authenticated (default)`, or `Authenticated only`.
2. **`authMode`** — map audience → `authMode`: anonymous or mixed → `UnAuth`; authenticated-only → `Auth`. Name the chosen value explicitly in the settled-facts report as a bare value (`authMode: UnAuth`).
3. **Post-deploy assertion** — after the channel is deployed in Step C, re-fetch the MessagingChannel and assert `embeddedConfig.authMode` matches the chosen value; if it doesn't, surface the discrepancy and stop the Web Chat branch. Always run this assertion.

This determines the MessagingChannel's `embeddedConfig.authMode`, which is set when the channel is deployed in Step C below. Choosing wrong silently breaks the deployment: the widget refuses to render on the Setup → ESD → "Test Enhanced Web Chat" page and for any anonymous visitor on the live site, with no error surfaced to the user. This is the single highest-risk decision in the Web Chat branch — previous runs defaulted to `Auth` and shipped a non-functional deployment that took manual debugging to discover. Ask explicitly and confirm the answer back to the user before proceeding.

Present three options:
1. **Public site / anonymous visitors only** → `authMode = UnAuth`.
2. **Both anonymous and authenticated visitors** *(default — recommended for any customer-facing portal)* → `authMode = UnAuth`. Despite the name, `UnAuth` *allows* both: guests chat anonymously, and signed-in users can upgrade the session by passing an `identityToken` at runtime.
3. **Authenticated visitors only** (no guests) → `authMode = Auth`. **Warn the user verbatim:** *"This requires your host app to mint a verified-user JWT for every visitor. The Setup → ESD → 'Test Enhanced Web Chat' button will not work because it loads the widget as a guest, and anonymous visitors on your Experience site will fail to load the chat. Pick this only if you have JWT issuance in place."*

Default to option 2 if the user is unsure. Never silently pick `Auth`. Never emit a legacy `esw.min.js` / Live Agent V1 bootstrap snippet — the V2 widget mounts via the `experience_messaging:embeddedMessaging` LWR component (Step C.3, Checkpoint 4 Phase B step 2).

## Step C — Provision (in order)

### C.0 — Resolve escalation queue

Run immediately after Step B (before any deploy), once the channel type is known.

**Query existing queues that already support the relevant SobjectType for this channel:**

| Channel | SobjectType |
|---|---|
| Web Chat / Help Portal / WhatsApp / SMS / Messaging | `MessagingSession` |
| Voice / Phone | `VoiceCall` |
| Email / Case | `Case` |

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

Branch via `AskUserQuestion`:
- **One or more queues found** → present each as an option (`{Name} ({DeveloperName})`), plus a final option *"Create a new queue for this agent"*. If the user picks an existing queue, capture its `DeveloperName` and skip queue-creation below.
- **Zero queues found** → inform the user no compatible queue exists and proceed to create one.

**If creating a new queue:**

1. Name: `{AgentLabel} Queue`, DeveloperName: `{AgentDevName}_Queue`
2. Create the `Group` record:
   ```bash
   QUEUE_ID=$(sf data create record --target-org $ORG \
     --sobject Group \
     --values "Type='Queue' Name='{AgentLabel} Queue' DeveloperName='{AgentDevName}_Queue'" \
     --json | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")
   ```
3. Grant the queue access to `MessagingSession`:
   ```bash
   sf data create record --target-org $ORG \
     --sobject QueueSobject \
     --values "QueueId='$QUEUE_ID' SobjectType='MessagingSession'"
   ```
4. Add the executing user to the queue:
   ```bash
   RUNNING_USER_ID=$(sf org display --target-org $ORG --json \
     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['userId'])")
   sf data create record --target-org $ORG \
     --sobject GroupMember \
     --values "GroupId='$QUEUE_ID' UserOrGroupId='$RUNNING_USER_ID'"
   ```

Capture the resolved `QUEUE_DEVELOPER_NAME` (either from an existing queue or the one just created). It is used in both Step C.1 (MessagingChannel `sessionHandlerQueue`) and Step C.2 (RoutingFlow queue lookup).

---

### C.1 — Outbound (Escalation) wiring is deferred to Phase 3, not created here

> **Do not create the RoutingFlow or touch the agent's connection block in this step.** Outbound escalation — asking the user, resolving the escalation queue, creating/reusing the RoutingFlow, adding the `connection customer_web_client:` block, and republishing the agent — is a single atomic unit owned entirely by `service-agentforce-channel-configure` Phase 3. Splitting flow-creation here from connection-wiring at Checkpoint 4 duplicates Phase 3's own sequencing and causes an extra, avoidable agent republish. Skip straight to Step C.2 (channel deploy) and inbound wiring; once inbound routing is confirmed, invoke Phase 3 immediately (see Checkpoint 3 Step 3 in `assets/help-agent-spec.md`) rather than deferring it to Checkpoint 4.

For reference, when Phase 3 runs for Web Chat it will use:
- Flow label: `{AgentLabel} Outbound Enhanced Chat Flow`
- DeveloperName: `{AgentDevName}_Outbound_Enhanced_Chat_Flow`
- `SERVICE_CHANNEL_DEV_NAME`: `sfdc_livemessage`, `SERVICE_CHANNEL_LABEL`: `Messaging`
- Connection key: `connection customer_web_client:` — not `connection messaging:` (see `service-agentforce-channel-configure`'s `agent-wiring.md`)

---

### C.2 — Deploy MessagingChannel

Deploy the messaging channel + omni-channel routing (`service-digital-engagement-channel-configure`, channel deploys INACTIVE). **Set `embeddedConfig.authMode` from the choice in Step B.** For `UnAuth`, also set `anonymousUserJwtExpirationTime` (e.g. `360`). For `Auth`, set `verifiedUserJwtExpirationTime` (e.g. `60`). Set `sessionHandlerQueue` to the `QUEUE_DEVELOPER_NAME` resolved in Step C.0.

   > **Prerequisite for ASA routing.** Ensure the bot is Active before invoking `service-digital-engagement-channel-configure` — it rejects ASA binding with "Only active Agentforce Service Agents are supported" otherwise. See that skill's SKILL.md for the deploy mechanics.

### C.3 — Activate MessagingChannel

Activate the MessagingChannel after the agent is Active (and re-verify at Checkpoint 4).

### C.4 — Create a NEW Embedded Service Deployment named `Help Chat`

Delegate to **`service-digital-engagement-deployment-configure`** with these inputs:

- **Operation**: `create`
- **Deployment type**: `Web`
- **Deployment name / DeveloperName**: `HelpChat` / MasterLabel `Help Chat`
- **Channel**: MessagingChannel DeveloperName from Step C.1 (skill will query the record Id)
- **hostDomain**: the customer domain from Step A (e.g. `support.acme.com`) — ties the widget's security key to that domain

The skill creates the ESD via `POST /connect/embeddedmessaging/deployment/setup` (V2, Connect API), binds the messaging channel at creation time so `isPublishSuccess: true` is returned, and auto-generates the `ESW_*` scaffolding site. **Do NOT re-point or re-use any existing ESD from a prior deployment.**

After the skill completes, capture the ESC Id:

```bash
sf data query --target-org $ORG --use-tooling-api \
  -q "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='HelpChat'" --json \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['result']['records'][0]['Id'])"
```

The ESD's endpoint URL (needed for the `siteEndpoint` attribute on the LWR component) is the `ESW_HelpChat_*` site row **without** the `vforcesite` suffix:

```bash
sf data query --target-org $ORG \
  -q "SELECT Name, UrlPathPrefix FROM Site WHERE Name LIKE 'ESW_HelpChat%' AND SiteType='ChatterNetworkPicasso'" --json
```

Pass `siteEndpoint` (`https://<myDomainStem>.my.site.com/<UrlPathPrefix>`) to Checkpoint 4 Phase B step 2.
### C.5 — Resolve deployment target (Experience Cloud site or own website)

Ask the user where they want to deploy the chat widget via `AskUserQuestion`:
- **"I'll embed it on my own website"** *(Recommended for most customers)* — skip Experience Cloud site creation. The ESD was already created above without a `<site>` reference; skip widget injection (Steps D.1–D.7). Proceed to Step D.8 for the embed snippet instructions.
- **"Deploy on a Salesforce Experience Cloud site"** — continue with the site resolution below.

**If Experience Cloud path:** Query for real (non-auto-generated) sites — both LWR and Aura:

```bash
sf data query --target-org $ORG --json \
  --query "SELECT Id, Name, MasterLabel, UrlPathPrefix, SiteType, Status FROM Site WHERE Status='Active' AND SiteType IN ('ChatterNetworkPicasso','ChatterNetwork') ORDER BY SiteType, Name" \
  | python3 -c "
import sys, json
recs = json.load(sys.stdin)['result']['records']
real = [r for r in recs if not r['Name'].startswith('ESW_')]
esw  = [r for r in recs if r['Name'].startswith('ESW_')]

for r in real:
    r['_type'] = 'LWR' if r['SiteType'] == 'ChatterNetworkPicasso' else 'Aura'

print(f'Real sites: {len(real)} ({sum(1 for r in real if r[\"_type\"]==\"LWR\")} LWR, {sum(1 for r in real if r[\"_type\"]==\"Aura\")} Aura) | ESW-filtered: {len(esw)}')
for r in real:
    print(f'  {r[\"MasterLabel\"]:40} ({r[\"_type\"]}) | /{r[\"UrlPathPrefix\"]}')
"
```

> **ESW filtering — why and how:** Every ESD auto-creates a pair of `Site` records named `ESW_{EsdName}_{timestamp}` (one Aura, one LWR). These are internal endpoint scaffolding, not real Experience Cloud destinations. SOQL `NOT LIKE` cannot be combined with `AND` in the `sf data query` CLI without a shell-quoting error, so filter them out in Python post-processing as shown above. If all sites after filtering are ESW-prefixed, treat as "zero real sites found."
>
> **Duplicate MasterLabels:** Each real Experience Cloud site generates two `Site` records with the same `MasterLabel` — one `ChatterNetwork` (Aura) and one `ChatterNetworkPicasso` (LWR). Both are shown to the user. The `SiteType` on the record the user picks determines which metadata layout path `service-digital-engagement-messaging-site-integrate` follows (LWR: patches `sfdc_cms__themeLayout/*/content.json` footer regions; Aura: patches `homeGuestLayout.json`).
>
> **Status value:** `Site.Status` is `'Active'` (not `'Live'`) on all org shapes tested. Using `'Live'` returns zero rows.

**Branch by what's found:**

- **Zero real sites found** → ask: deploy on own website (give snippet), or create a new LWR Experience Cloud site via the Self Service Connect API (`POST /connect/self-service/site`, status via `GET /connect/self-service/site/status/{jobId}`, called through the API-catalog MCP `discover`/`describe`/`dispatch` tools when connected). Follow **Creating a new LWR site** below (directly under this step's Site query). This is the preferred site-creation route; `POST /connect/communities`, `sf community create`, or hand-built site metadata are last-resort alternatives only (see the Site creation rule in SKILL.md). When the MCP tools are unavailable, use the `sf api request rest` fallback below.

- **Real sites found** → present using the **long-list presentation rules** from SKILL.md. Do not label sites as LWR/Aura — show each as `{MasterLabel} (/{UrlPathPrefix})`. Always include "Create a new Experience Cloud site" and "Deploy on my own website (get snippet)" as fixed options on the final page.

**After the user selects:**

- **Site selected (either type)** → delegate to `service-digital-engagement-messaging-site-integrate`. The skill reads `SiteType` from the selected site's record and patches the correct layout automatically (LWR: `sfdc_cms__themeLayout/*/content.json` footer regions; Aura: `homeGuestLayout.json` and `homeAuthenticated.json`). After the skill completes, confirm: *"The chat widget has been added to [site name] and will appear as a floating overlay on every page."* Publish the site and verify the smoke-test URL returns 200. This is where widget placement actually happens — Checkpoint 4 Phase B only verifies it landed; if that verification fails, Phase B's repair procedure re-runs the same injection this step performed.
- **Own website selected** → proceed to Step D.8 snippet instructions.

Do not filter by any hardcoded site name or `UrlPathPrefix` value — the correct site depends on the customer's org and is not knowable up front.

### Site creation rule and creating a new LWR site

**Site creation rule (applies to every path, read before anything else).**

Whenever a site must be created — the user asks for it directly, Web Chat finds no site, or a Help Portal / any other branch needs one — create it with the Self Service Connect API `POST /connect/self-service/site`, and track it with `GET /connect/self-service/site/status/{jobId}`. Use the API-catalog MCP tools (`discover` / `describe` / `dispatch`) if they are connected; otherwise, call the same endpoints with `sf api request rest`. Treat `POST /connect/communities`, `sf community create`, a site-generation skill, and hand-built CustomSite / Network / ExperienceBundle metadata as a **last resort only**: never reach for them first, and never because they appear to work. If the endpoint is unavailable (404, or API version below 67.0) or the job ends in `Error`, say so and offer the own-website snippet or a retry first; use one of the alternatives only if the user declines those and explicitly approves it. **Before calling it, always ask the user for two inputs, in the current conversation, even when the request is a direct "create a site":** (1) the **site name** (`siteName`), and (2) **whether the site must be publicly accessible** (`enableForGuest`: yes → `true`, no → `false`). Never invent a site name, never default `enableForGuest`, and never reuse values from an earlier session or a summary; if the user already stated one in this conversation, confirm it rather than re-asking. Do not send the request until both are answered. The exact steps follow.

**Creating a new LWR site (Zero-sites branch, or the user picks "Create a new LWR site").** Follow the **Site creation rule** above. The endpoints are exposed to the API catalog and MCP (min-version 264), so resolve them with `discover` / `describe` (e.g. query "create experience cloud site self service") and call them with `dispatch`.
1. **Ask the user for the site name** (`siteName`, free text) and **whether the site must be publicly accessible** (guest access; `AskUserQuestion` with Yes / No). Both are required inputs: do not assume either, do not call the API until both are answered, and do not ask about one without the other.
2. **POST `/connect/self-service/site`** with `siteType: "LWR"` and `publish: false` (the site is created unpublished and stays that way until the user publishes it in Setup; tell them so). `siteName` and `enableForGuest` come **only** from the user's answers in step 1 (`enableForGuest` is `true` if they want public access, otherwise `false`); only `siteType` and `publish` are fixed:

   ```json
   { "siteName": "<user's site name>", "siteType": "LWR", "publish": false, "enableForGuest": <true|false from the user's answer> }
   ```

   The call is asynchronous. The response carries `jobId` and `status: Queued`. Requires Self-Service Concierge to be enabled in the org.
3. **Poll `GET /connect/self-service/site/status/{jobId}`** until `status` is `Complete` (other values: `Queued`, `InProgress`, `Error`). On `Complete`, capture `siteName`, `urlPathPrefix`, and `siteUrl` from the response. On `Error`, surface the `error` text verbatim, stop, and offer the own-website fallback or a retry with the user's go-ahead.
4. **Re-run the Site SOQL** above to pick up the new site record (use `urlPathPrefix` to match it), then continue as for any selected site — ESD creation and widget placement (`service-digital-engagement-messaging-site-integrate`) follow in `references/channel-web-chat.md`.

**Direct REST fallback (only when the API-catalog MCP tools are unavailable)** — same endpoints, same body, using the org's API version (`$API_VERSION`, 67.0 or later). Write the body to a scratch file outside the skill directory:

```bash
cat > /tmp/site-create-body.json <<'EOF'
{ "siteName": "<user's site name>", "siteType": "LWR", "publish": false, "enableForGuest": <true|false from the user's answer> }
EOF
sf api request rest "/services/data/v${API_VERSION}/connect/self-service/site" \
  --method POST --body @/tmp/site-create-body.json --target-org $ORG

# poll until status is Complete (or Error)
sf api request rest "/services/data/v${API_VERSION}/connect/self-service/site/status/${JOB_ID}" \
  --method GET --target-org $ORG
```

### C.6 — Wire up knowledge citations The script's `knowledge:` block ships with `citations_enabled: True` and `citations_url: ""` (the URL isn't knowable until a site exists). Once the target site's public URL is resolved here, set `citations_url` to that URL so knowledge answers cite working links. If no customer-facing site URL can be resolved, set `citations_enabled: False` instead — do not leave citations enabled with an empty URL, or answers render broken/empty citation links.

## Step D.8 — Post-setup next steps (Checkpoint 4, after go-live)

Print these after the ESD is published and the channel is Active.

**If deployed on an Experience Cloud site:**
- Test URL: `https://{siteBaseUrl}/{siteUrlPathPrefix}/s` — open in an incognito browser as a guest. The floating chat launcher should appear. Send a message to confirm the agent responds.
- Test escalation: say *"I need to speak to a human"* — the agent should transfer to the queue resolved in Step C.0. This requires at least one agent to be available in the Omni-Channel widget in the Service Console; set your own status to Available to test.

**If deploying on own website:**
- Direct the user to Setup → Embedded Service Deployments → {ESD Name} → **Get Code** to copy the JavaScript snippet. The snippet is org-specific and must be retrieved from Setup — do not attempt to generate or reconstruct it.
- The snippet goes in the `<head>` or before `</body>` of any page where the widget should appear. It must be served over HTTPS.

**Testing checklist (both paths):**
1. Agent responds to a greeting → channel is live
2. Agent answers a question from the knowledge source → grounding is working
3. Agent escalates to a human when asked → RoutingFlow and queue are wired correctly (requires an agent available in Omni-Channel)
4. Widget closes and reopens without losing session → widget state is healthy

## Handoff to Checkpoint 4

After Web Chat provisioning, the flow returns to the spec: Checkpoint 4, Phase A (silent pre-flight — Data Cloud access, ADL grounding, channel-active assertion) then Phase B (embed + go-live, including widget placement and Embedded Service Deployment publish). Those gates live in the spec (`assets/help-agent-spec.md` §4.4); do not re-implement them here.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall