customer-assist

name	customer-assist
description	Configure Webex Calling Customer Assist (CX Essentials) using wxcli CLI commands: screen pop, wrap-up reasons, queue call recording, supervisors, and available agents. Guides the user from prerequisites through configuration and verification. NOT for: standard call queues/hunt groups (use configure-features) or full Contact Center queues/agents (use contact-center skill — CX Essentials is a Calling add-on, not WxCC).
allowed-tools	Read, Grep, Glob, Bash
argument-hint	["feature-type"]

Configure Customer Assist Workflow

Checkpoint — do NOT proceed until you can answer these:

1. How do you list Customer Assist call queues? (Answer: wxcli call-queue list --has-cx-essentials true — they are hidden from the default call-queue list output.)
2. What is the workaround for the supervisor delete bug? (Answer: delete-supervisors-config-1 returns 204 but the supervisor persists. Instead, use update-supervisors with action: DELETE on each agent — removing the last agent auto-removes the supervisor.)

If you cannot answer both, you skipped reading this skill. Go back and read it.

Step 1: Load references

1. Read docs/reference/call-features-additional.md — Customer Assist data models, screen pop, wrap-up reasons, queue recording, available agents
2. Read docs/reference/location-recording-advanced.md — Supervisors data models, API methods, key behaviors

Mandatory --help verification: Before constructing any wxcli command, run wxcli <group> --help to verify the subcommand exists, then wxcli <group> <subcommand> --help to verify the exact flags (e.g. wxcli customer-assist --help for CX queue management — and note CX queues require --has-cx-essentials true on call-queue commands or they vanish from listings, known issue #7). Do NOT rely on examples in this skill or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests.

Step 2: Verify auth token

Before any API calls, confirm the user has a working auth token:

wxcli whoami

If this fails, stop and resolve authentication first (wxcli configure). Required scopes:

Operation	Read Scope	Write Scope
Screen pop, wrap-up, agents, supervisors	spark-admin:telephony_config_read	spark-admin:telephony_config_write
Queue call recording	spark-admin:people_read	spark-admin:people_write

Step 3: Identify which feature(s) to configure

Ask the user which feature they want to configure. Present this decision matrix if they are unsure:

Need	Feature	CLI Group
Pop a CRM/ticketing URL when agent receives a queued call	Screen Pop	wxcli customer-assist
Post-call categorization codes for agents	Wrap-Up Reasons	wxcli customer-assist
Record calls on a queue for QA/compliance/training	Queue Call Recording	wxcli customer-assist
Assign supervisors to monitor/coach/barge agents	Supervisors	wxcli call-queue
List agents with or without Customer Assist licensing	Available Agents	wxcli customer-assist

Step 4: Check prerequisites

Before configuring any feature, verify these exist:

4a. Location exists

wxcli locations list --output json

4b. Customer Assist queue exists

All Customer Assist features are per-queue configurations. Customer Assist queues are separate from regular queues — they do not appear in the default call-queue list output.

# List Customer Assist queues (MUST use --has-cx-essentials true)
wxcli call-queue list --has-cx-essentials true --output json

If no Customer Assist queue exists, create one. Customer Assist queues require callPolicies via --json-body:

wxcli call-queue create LOCATION_ID --name "Queue Name" --has-cx-essentials true \
  --json-body '{"name":"Queue Name","extension":"XXXX","callPolicies":{"policy":"SIMULTANEOUS"}}'

IMPORTANT: A regular queue (created without --has-cx-essentials true) will return error 28018 on all Customer Assist endpoints. The queue must be created with the --has-cx-essentials true flag. The callPolicies field is mandatory for Customer Assist queues but not for regular queues.

4c. Customer Assist licensing

Confirm agents have Customer Assist licenses:

wxcli customer-assist list-available-agents LOCATION_ID --has-cx-essentials true

If no agents are returned, Customer Assist licenses must be assigned first (use manage-licensing skill).

4d. Feature-specific prerequisites

Feature	Additional Prerequisites
Screen Pop	Call queue must exist. No additional requirements.
Wrap-Up Reasons	Call queue must exist. Org-level reasons must be created before queue assignment.
Queue Call Recording	Call queue must exist. Recording vendor must be configured at org/location level (see wxcli call-recording). Requires spark-admin:people_read/people_write scopes (different from other Customer Assist features).
Supervisors	At least one agent must be assigned when creating. Supervisor must be a calling-enabled user.
Available Agents	Location must exist.

Step 5: Gather configuration and present deployment plan -- [SHOW BEFORE EXECUTING]

Based on the selected feature, collect the required parameters from the user. Always present the plan before executing.

---

Screen Pop

Collect from user:

Parameter	Required	Notes
Location ID	Yes	Positional argument
Queue ID	Yes	Positional argument
Enabled	Yes	--enabled / --no-enabled
Screen pop URL	Yes (if enabling)	CRM or ticketing system URL
Desktop label	No	Label for the config
Query params	No	Requires --json-body (not available as explicit flags)

CLI commands:

# View current screen pop config
wxcli customer-assist show-screen-pop LOCATION_ID QUEUE_ID -o json

# Simple: enable with URL
wxcli customer-assist update-screen-pop LOCATION_ID QUEUE_ID \
  --enabled --screen-pop-url "https://crm.example.com/lookup"

# Full: enable with URL, label, and query params (requires --json-body)
wxcli customer-assist update-screen-pop LOCATION_ID QUEUE_ID --json-body '{
  "enabled": true,
  "screenPopUrl": "https://crm.example.com/lookup",
  "desktopLabel": "Customer Lookup",
  "queryParams": {"caller_id": "{{callerNumber}}", "queue": "{{queueName}}"}
}'

NOTE: Query parameters (queryParams) are only available via --json-body. The --screen-pop-url, --enabled, and --desktop-label flags cover the simple case. Use --json-body for the full configuration including query params.

---

Wrap-Up Reasons

Wrap-up reasons are a two-level configuration: org-level reasons, then per-queue assignment.

Org-level parameter table:

Parameter	Required	Notes
Name	Yes	--name flag
Description	No	--description flag
Queues	No	List of queue IDs — requires --json-body (not available as explicit flag)
Assign all queues	No	--assign-all-queues-enabled flag

Queue-level parameter table:

Parameter	Required	Notes
Location ID	Yes	Positional argument
Queue ID	Yes	Positional argument
Wrap-up timer enabled	No	--wrapup-timer-enabled / --no-wrapup-timer-enabled
Wrap-up timer (seconds)	No	--wrapup-timer (default 60)
Default wrap-up reason ID	No	--default-wrapup-reason-id
Wrap-up reasons list	No	List of reason IDs — requires --json-body

CLI commands:

# --- Org-level reason management ---

# List all wrap-up reasons
wxcli customer-assist list

# Create a reason (simple — assign to queues later)
wxcli customer-assist create --name "Issue Resolved" --description "Customer issue resolved on the call"

# Create a reason AND assign to specific queues (requires --json-body)
wxcli customer-assist create --json-body '{
  "name": "Issue Resolved",
  "description": "Customer issue resolved on the call",
  "queues": ["QUEUE_ID_1", "QUEUE_ID_2"]
}'

# Validate a reason name before creating
wxcli customer-assist validate-wrap-up --name "Issue Resolved"

# Show reason details (includes assigned queues)
wxcli customer-assist show REASON_ID -o json

# Update a reason (incremental queue assignment)
wxcli customer-assist update REASON_ID --json-body '{
  "queuesToAssign": ["QUEUE_ID_3"],
  "queuesToUnassign": ["QUEUE_ID_1"]
}'

# List queues not yet assigned to a reason
wxcli customer-assist list-available-queues REASON_ID

# Delete a reason
wxcli customer-assist delete REASON_ID --force

# --- Per-queue wrap-up settings ---

# View queue wrap-up settings
wxcli customer-assist list-settings LOCATION_ID QUEUE_ID -o json

# Update queue wrap-up timer and assign reasons
wxcli customer-assist update-settings LOCATION_ID QUEUE_ID --json-body '{
  "wrapupTimerEnabled": true,
  "wrapupTimer": 60,
  "wrapupReasons": ["REASON_ID_1", "REASON_ID_2"],
  "defaultWrapupReasonId": "REASON_ID_1"
}'

NOTE: The queues array on create and the wrapupReasons array on update-settings require --json-body. The CLI flags only cover scalar fields (--name, --description, --wrapup-timer-enabled, --wrapup-timer). For queue assignment at creation time, use --json-body.

NOTE: Queue assignment on update is incremental — use queuesToAssign and queuesToUnassign, not a full replacement list.

---

Queue Call Recording

Collect from user:

Parameter	Required	Notes
Location ID	Yes	Positional argument
Queue ID	Yes	Positional argument
Enabled	Yes	--enabled / --no-enabled
Record mode	No	--record — only Always is live-verified
Notification / repeat / announcement	No	Nested objects — require --json-body

# View current queue recording settings
wxcli customer-assist show-call-recordings LOCATION_ID QUEUE_ID -o json

# Simple: turn recording on for every call to the queue
wxcli customer-assist update-call-recordings LOCATION_ID QUEUE_ID --enabled --record Always

# Full: notification, repeat, and start/stop announcement (nested -> --json-body)
wxcli customer-assist update-call-recordings LOCATION_ID QUEUE_ID --json-body '{
  "enabled": true,
  "record": "Always",
  "notification": {"type": "Beep", "enabled": true},
  "repeat": {"interval": 30, "enabled": true},
  "startStopAnnouncement": {"internalCallsEnabled": true, "pstnCallsEnabled": true}
}'

# ALWAYS read back — a 2xx does NOT mean the write applied (see rule 20)
wxcli customer-assist show-call-recordings LOCATION_ID QUEUE_ID -o json

NOTE: Recording settings live ONLY in this sub-resource. The call queue object carries no recording fields, so call-queue show/update cannot read or write them — verified live 2026-07-14. Do not fall back to call-queue update --json-body; it silently cannot work.

NOTE: Cisco's published OpenAPI spec omits this endpoint, so the commands are generated from a local additive overlay (specs/overlays/webex-cloud-calling.overlay.json). The endpoint is live and verified, but it is unpublished — Cisco makes no compatibility promise for it. If these commands ever start 404ing, that is the likely cause. Full data model + gotchas: docs/reference/call-features-additional.md → "Queue Call Recording — data model".

---

Supervisors

Supervisor commands live under wxcli call-queue, not wxcli customer-assist. All commands must include --has-cx-essentials true when working with Customer Assist supervisors (without it, commands default to CX Basic).

Collect from user (for create):

Parameter	Required	Notes
Supervisor person ID	Yes	--id flag — the person's ID (not a separate supervisor entity ID); must be a calling-enabled user
Agents	Yes	List of agent IDs — requires --json-body
Has Customer Assist	Yes (for Customer Assist)	--has-cx-essentials true

CLI commands:

# --- Discovery ---

# List all Customer Assist supervisors
wxcli call-queue list-supervisors --has-cx-essentials true

# List available supervisors (not yet assigned)
wxcli call-queue list-available-supervisors --has-cx-essentials true

# List available agents for supervisor assignment
wxcli call-queue list-available-agents-supervisors --has-cx-essentials true

# --- Create ---

# Create a supervisor with agents (--id is required AND must be in --json-body)
wxcli call-queue create-supervisors --has-cx-essentials true \
  --id SUPERVISOR_PERSON_ID --json-body '{"id": "SUPERVISOR_PERSON_ID", "agents": [{"id": "AGENT_ID_1"}, {"id": "AGENT_ID_2"}]}'

# --- Read ---

# Show supervisor's assigned agents
wxcli call-queue show-supervisors SUPERVISOR_ID --has-cx-essentials true -o json

# --- Update ---

# Add/remove agents (incremental)
wxcli call-queue update-supervisors SUPERVISOR_ID --has-cx-essentials true --json-body '{
  "agents": [
    {"id": "AGENT_ID_3", "action": "ADD"},
    {"id": "AGENT_ID_1", "action": "DELETE"}
  ]
}'

# --- Delete ---

# Delete a specific supervisor
wxcli call-queue delete-supervisors-config-1 SUPERVISOR_ID --force

# Delete ALL supervisors in the org — the CLI cannot scope this (see WARNING)
wxcli call-queue delete-supervisors-config --force

WARNING: delete-supervisors-config --force removes all supervisors in the org, and the CLI offers no way to narrow it: the API scopes this delete with a request body, which the generator does not render for DELETE verbs (known issue #21). To remove specific supervisors, use delete-supervisors-config-1 SUPERVISOR_ID one at a time, or the raw HTTP fallback. Omitting --force triggers a confirmation prompt.

NOTE: SUPERVISOR_ID in these commands is the supervisor's person ID, not a separate supervisor entity ID. Use wxcli call-queue list-supervisors --has-cx-essentials true to find supervisor person IDs.

NOTE: Runtime supervisor capabilities (silent monitor, whisper coach, barge in, take over) activate automatically once the supervisor-agent relationship is configured. No additional API setup is needed — these are built into the Webex app.

---

Available Agents

# List all agents at a location
wxcli customer-assist list-available-agents LOCATION_ID

# List only agents with Customer Assist (Customer Assist) license
wxcli customer-assist list-available-agents LOCATION_ID --has-cx-essentials true

# List only agents with CX Basic license
wxcli customer-assist list-available-agents LOCATION_ID --has-cx-essentials false

---

Deployment Plan Template

DEPLOYMENT PLAN
===============
Feature: Customer Assist — [sub-feature]
Location: [name] ([location_id])
Queue: [queue_name] ([queue_id])

Configuration:
  [Feature-specific settings listed here]

Prerequisites verified:
  ✓ Location exists
  ✓ Call queue exists
  ✓ Customer Assist licenses assigned ([N] agents)
  ✓ [Feature-specific prereqs]

Commands to execute:
  wxcli customer-assist [command] ...

Proceed? (yes/no)

Wait for user confirmation before executing.

Step 6: Execute via wxcli

Run commands sequentially. Handle errors explicitly:

• 400 with code 28018: Customer Assist is not enabled on this queue — create the queue with --has-cx-essentials true or use a Customer Assist queue (see Step 4b)
• 401/403: Token expired or insufficient scopes — run wxcli configure
• 409: Name or resource conflict — ask user for alternate
• 400: Validation error — read the error message and fix the parameter
• 400 with code 25008: Missing required field — use --json-body for full control
• 400 with code 4003 / "Target user not authorized": Endpoint requires user-level OAuth, not admin token
• 404 with code 4008: Target user needs a Webex Calling license
• 405 with code 25409: Workspace requires Professional license

Step 7: Verify creation

After configuration, fetch the details back and confirm:

# Verify screen pop
wxcli customer-assist show-screen-pop LOCATION_ID QUEUE_ID -o json

# Verify wrap-up reasons (org-level)
wxcli customer-assist list -o json
wxcli customer-assist show REASON_ID -o json

# Verify wrap-up settings (per-queue)
wxcli customer-assist list-settings LOCATION_ID QUEUE_ID -o json

# Verify queue recording — the read-back IS the verification (see rule 20)
wxcli customer-assist show-call-recordings LOCATION_ID QUEUE_ID -o json

# Verify supervisors
wxcli call-queue list-supervisors --has-cx-essentials true -o json
wxcli call-queue show-supervisors SUPERVISOR_ID --has-cx-essentials true -o json

Step 8: Report results

Present the configuration results:

CUSTOMER ASSIST CONFIGURED
===========================
Feature: [sub-feature]
Queue: [queue_name]
Location: [location_name]

Configuration applied:
  [Feature-specific summary]

Verification:
  ✓ [Feature] confirmed via read-back

Next steps:
  - [Feature-specific next steps]
  - [e.g., "Assign more agents to supervisor via update-supervisors"]
  - [e.g., "Configure additional queues with the same wrap-up reasons"]

---

Critical Rules

1. All Customer Assist features require a Customer Assist queue. Screen pop, queue recording, and wrap-up reasons are per-queue configurations. The queue must be created with --has-cx-essentials true — a regular queue returns error 28018. Use wxcli call-queue list --has-cx-essentials true to find existing Customer Assist queues (they are hidden from the default call-queue list).
2. Always show the deployment plan (Step 5) and wait for user confirmation before executing.
3. Always pass --has-cx-essentials true on supervisor commands. Without it, commands default to CX Basic supervisors. This applies to list-supervisors, create-supervisors, show-supervisors, update-supervisors, list-available-supervisors, and list-available-agents-supervisors.
4. Supervisor commands live under wxcli call-queue, not wxcli customer-assist. The supervisor API base path (/telephony/config/supervisors) was grouped with call queues in the OpenAPI spec. The cx-essentials group handles wrap-up reasons, screen pop, queue recording, and available agents.
5. A supervisor must have at least one agent when created via create-supervisors.
6. delete-supervisors-config --force can remove ALL supervisors in the org. The bulk delete endpoint has a delete_all option. Always confirm scope before executing.
7. Queue call recording requires different scopes. Queue recording uses spark-admin:people_read / spark-admin:people_write, while all other Customer Assist features use spark-admin:telephony_config_read / spark-admin:telephony_config_write.
8. Wrap-up reason queue assignment is incremental. Use queuesToAssign and queuesToUnassign on update — not a full replacement list.
9. show-supervisors returns the supervisor's assigned agents, not the supervisor's own details. The response is a list of agents, not supervisor metadata.
10. Per-queue features need both location_id and queue_id. Screen pop, queue recording, and wrap-up settings are scoped to a specific queue within a specific location.
11. queryParams on screen pop requires --json-body. The --screen-pop-url, --enabled, and --desktop-label flags cover the simple case. For query parameters (passing caller data to the CRM URL), use --json-body.
12. queues array on wrap-up reason create requires --json-body. To assign a reason to specific queues on creation, use --json-body. Alternatively, create the reason first, then assign queues via update.
13. Runtime supervisor capabilities are automatic. Silent monitor, whisper coach, barge in, and take over activate once the supervisor-agent relationship is configured. No additional API setup is needed.
14. Recording vendor must be configured first. Queue call recording depends on an org-level or location-level recording vendor configuration. Check with wxcli call-recording show -o json before enabling queue recording.
15. Customer Assist queues are hidden from default call-queue list. You must pass --has-cx-essentials true to see them. Without the flag, only regular (non-Customer Assist) queues are returned.
16. Queue recording schema is VERIFIED (2026-07-14). notification, repeat, and startStopAnnouncement are real and writable — proven by live PUT-then-GET read-back. A previous audit (2026-07-01) called this schema "fabricated"; that verdict was wrong on both counts. The fields are real (they live in the separate cxEssentials/callRecordings sub-resource, which the audit never called — it only checked the call queue payload). And the old show-queue-recording/update-queue-recording commands were not fabricated either: git history shows they were hand-written on 2026-03-21 and silently destroyed by a regen two days later, because they had been placed inside a generator-owned file. Nothing here was invented — it was built, then overwritten, and the docs outlived the code. Full data model: docs/reference/call-features-additional.md → "Queue Call Recording — data model".
17. create-supervisors requires id in both --id flag and --json-body. The --id flag is a required CLI option. When using --json-body, include "id" in the JSON body too, since --json-body overrides flag-built body fields.
18. To remove a Customer Assist supervisor, remove all their agents first. The DELETE endpoint (delete-supervisors-config-1) returns 204 but the supervisor may persist. Instead, use update-supervisors with action: DELETE on each agent. When the last agent is removed, the supervisor is automatically deleted.
19. Customer Assist queue creation requires callPolicies. Unlike regular queues, CX queues require the callPolicies field (e.g., {"policy":"SIMULTANEOUS"}). This must be passed via --json-body since it's not available as a CLI flag.
20. On queue recording, a success response proves NOTHING — always read back. update-call-recordings returns 204 even when it silently discards what you sent. Live-verified: a PUT of {"bogusFieldXyz": "nonsense"} returned 204 and the field never appeared on read-back. Always follow any update-call-recordings with show-call-recordings and confirm the value you set is actually present. Never report queue recording as configured based on the update command's exit code alone.
21. Queue recording PUT is a partial merge, not a replace. Omitted fields keep their previous value (verified: record stayed Always across a PUT that omitted it). You do not need to resend the full object to change one field — and you cannot clear a field by omitting it.
22. Queue recording's response schema changes with enabled. When recording is off, the record field and the postCallRecordingSettings / announcements objects are absent from the GET entirely. Their absence does not mean "unsupported" — enable recording first, then re-read.

---

Context Compaction Recovery

If context compacts mid-execution, recover by:

1. Read the deployment plan from docs/plans/ to recover what was planned
2. Check what's already been configured: run the relevant show / list commands
3. Resume from the first incomplete step