Skip to main content
skill CX Codex

service-omni-service-channel-configure — Claude Code skill: setup

service-omni-service-channel-configure is a Claude Code skill that finds or creates a ServiceChannel for Case, Incident, MessagingSession, or VoiceCall. It runs during Omni-Channel routing setup.

Apache-2.0 106 installs ★ 1,183 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add forcedotcom/sf-skills --skill service-omni-service-channel-configure -a claude-code
Open on GitHub

What service-omni-service-channel-configure does

The skill checks Salesforce for a ServiceChannel linked to the selected sObject and reuses it when found. If discovery returns nothing, scripts/deploy-and-report.sh deploys the matching canonical XML asset. Discovery uses the Tooling API because ServiceChannel is a Tooling entity in v66.0. Each invocation handles one sObject.

The target org must be authenticated through the sf CLI with a My Domain URL and have a Service Cloud license. The environment needs sf 2.139.6 or newer and jq 1.6 or newer. Omni-Channel base settings must be enabled. Incident also needs Incident Management, while MessagingSession needs Enhanced Messaging. Missing prerequisites can block the run or produce INVALID_TYPE.

Supported entities are Case, Incident, MessagingSession, and VoiceCall. Existing standard and custom channels are left unchanged, and agent capacity belongs in PresenceUserConfig.Capacity. The result is one JSON object with created, reused, or blocked status.

What it helps with

  • discover an existing ServiceChannel for a routable sObject
  • create the first channel for Incident
  • add VoiceCall or Incident routing to Omni-Channel
  • avoid Salesforce errors from duplicate channel deployment
  • return a JSON report for channel creation or reuse

Example prompts for the agent

  • Configure a ServiceChannel for Case in the org with bash scripts/deploy-and-report.sh <org-alias> Case.
  • Add Incident routing to Omni-Channel with bash scripts/deploy-and-report.sh <org-alias> Incident.
  • Check the VoiceCall channel and return its JSON report with bash scripts/deploy-and-report.sh <org-alias> VoiceCall.

How to install service-omni-service-channel-configure

1Skills CLI (Vercel)

npx skills add forcedotcom/sf-skills --skill service-omni-service-channel-configure -a claude-code

2Manually: put the files in place

~/.claude/skills/service-omni-service-channel-configure/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-omni-service-channel-configure/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about service-omni-service-channel-configure

How do I install service-omni-service-channel-configure in Claude Code?

Run npx skills add forcedotcom/sf-skills --skill service-omni-service-channel-configure -a claude-code, then open ~/.claude/skills/service-omni-service-channel-configure/SKILL.md.

What does service-omni-service-channel-configure do?

It checks EntityDefinition and queries the Tooling API for a ServiceChannel linked to one supported sObject. An existing channel is reused; when discovery finds none, the skill deploys the matching canonical XML asset.

What does service-omni-service-channel-configure require?

It requires an org authenticated through the sf CLI with a My Domain URL, a Service Cloud license, sf 2.139.6 or newer, and jq 1.6 or newer. Omni-Channel base settings and OrgPermissions.LightningService are also required; Incident needs Incident Management and MessagingSession needs Enhanced Messaging.

Source text

SKILL.md · Apache-2.0
---
name: service-omni-service-channel-configure
description: "Use to ensure exactly one ServiceChannel exists on a Salesforce org for a routable sObject (Case | Incident | MessagingSession | VoiceCall), reusing any standard or custom channel already bound to that sObject and only deploying a canonical template when none exists. Salesforce enforces one ServiceChannel per RelatedEntity, so the skill detects via the Tooling API first. Standard channels ship for Case (Cases), MessagingSession (sfdc_livemessage), VoiceCall (sfdc_phone); Incident has none. Triggers: configure ServiceChannel for Case/Incident/Messaging/Voice routing, add Incident or Voice routing to Omni. Do not use to tune per-sObject capacity (use PresenceUserConfig.Capacity), to reset a mis-configured channel to canonical shape, or for sObjects outside Case/Incident/MessagingSession/VoiceCall."
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  version: "1.0"
  domains: ["Service"]
  minApiVersion: "66.0"
  relatedSkills:
    - "service-omni-base-settings-configure"
  accessCheck: "OrgPermissions.LightningService"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.139.6"
---

# service-omni-service-channel-configure

Ensure exactly one `ServiceChannel` is present for a routable sObject, reusing whatever is already bound (Salesforce standard or a pre-existing custom channel) and deploying the skill's canonical v66 template only when none exists. Salesforce enforces one ServiceChannel per `RelatedEntity`, so the skill detects first and never deploys blindly — deploying a second channel for an sObject that already has one fails with "This Salesforce object is already in use by another Service channel." It handles one sObject per call; callers configuring multiple sObjects invoke it once for each sObject, after `service-omni-base-settings-configure` has enabled Omni-Channel.

| sObject | Standard channel (if any) | Canonical asset |
|---|---|---|
| `Case` | `Cases` | `Cases.serviceChannel-meta.xml` |
| `Incident` | none (Incident Management sObject) | `Incidents.serviceChannel-meta.xml` — deployed on first run |
| `MessagingSession` | `sfdc_livemessage` | `MessagingSessions.serviceChannel-meta.xml` — deployed only if the standard channel is missing |
| `VoiceCall` | `sfdc_phone` | `VoiceCalls.serviceChannel-meta.xml` — deployed only if the standard channel is missing |

## Inputs

```bash
bash scripts/deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall]
```

- `org-alias` (required).
- `sobject_type` (optional, default `Case`) — one of `Case | Incident | MessagingSession | VoiceCall`.

## Preconditions and safety

- Target org authenticated via `sf` CLI (My Domain URL), Service Cloud license, `sf` CLI ≥ 2.139.6.
- Omni-Channel base settings enabled (`service-omni-base-settings-configure`) — `ServiceChannel` is only queryable/writable when `enableOmniChannel=true`; a `INVALID_TYPE` on deploy means base settings are off.
- `Incident` requires the Incident Management feature enabled; `MessagingSession` requires Enhanced Messaging. The skill verifies `EntityDefinition` first and blocks with a click-path when the target sObject is absent.

## Run

`deploy-and-report.sh` performs the prereq check, discovery, and (only when needed) deploy, then emits the report:

1. **Prereq** — confirm the target sObject is queryable via `EntityDefinition`; block with a click-path otherwise.
2. **Discover** — query the Tooling API for a `ServiceChannel` with `RelatedEntity = <sobject_type>`. `ServiceChannel` is a Tooling entity on v66; the standard Data API returns `INVALID_TYPE`. A hit means reuse.
3. **Deploy** (only when nothing was found) — `sf project deploy start` of the canonical XML (`Cases` | `Incidents` | `MessagingSessions` | `VoiceCalls`); a `Changed` state is `created`, `Unchanged` is `reused`.

## Behavior

**Detect-then-reuse-or-deploy.** Because Salesforce rejects a second channel per `RelatedEntity`, deploy-first is unsafe: an operator who renamed the standard `Cases` channel would hit the "already in use" error instead of gracefully reusing. Tooling discovery is fast and returns both the reuse decision and the discovered `DeveloperName` in one call. The trade-off is that the skill cannot tell "our canonical shape matches" from "some custom channel is bound" — an operator with a non-canonical channel gets `reused` and their channel is left untouched (v1 never overwrites operator state).

**Capacity model.** The canonical assets use `TAB_BASED` for every variant. `STATUS_BASED` requires companion fields whose full schema is undocumented, so it is out of scope; per-agent capacity tuning belongs to `PresenceUserConfig.Capacity`, not this skill.

**Concurrency.** If a deploy fails with "already in use," another process created the channel between discovery and deploy; the skill soft-fails and a re-run reuses it.

## Output contract

A single JSON object per invocation with `status` ∈ `created` | `reused` | `blocked`, plus `sobject_type`, `channel_developer_name`, `channel_id`, `channel_origin`, `target_capacity_model`, `target_related_entity_type`, `before_state`, `deploy_id`, `manual_actions`, and `blocking_issue`.

- `reused` — an existing channel was found (discovery hit, or a deploy returned `Unchanged`).
- `created` — no channel existed; the canonical XML deployed with `Changed`.
- `blocked` — the sObject is not on the org, base settings are off (`INVALID_TYPE`), or a race left the channel already in use.
- `channel_origin` is one of `salesforce_standard` (an `sfdc_*` name or `Cases`), `canonical_asset` (a shipped asset name), `canonical_template` (freshly deployed this run), or `custom` (a pre-existing org-specific channel).
- `channel_id` is populated whenever a channel exists (`null` on `blocked`); `deploy_id` is populated only on the deploy branch; `blocking_issue` is non-null only when `status: blocked`.

## Limitations

- One sObject per invocation.
- Only `Case`, `Incident`, `MessagingSession`, `VoiceCall` are supported — extend by adding an `assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml` file and a dispatcher branch.
- Always reuses an existing channel; it does not reset a mis-configured channel to canonical shape.

## References

| File | When to read |
|---|---|
| `references/api-notes.md` | On unexpected discovery results, deploy failures, or sObject-specific schema questions |

© forcedotcom · Apache-2.0 · forcedotcom/sf-skills

Similar skills

All skills for Backend and APIs →

From the same set232

The whole set →
service-omni-routing-flow-deploy The service-omni-routing-flow-deploy Claude Code skill deploys an Omni-Channel routing Flow for Case or VoiceCall. It handles requests to route work to a queue or by skill, then checks the result. CX Codex +1 116installs dx-lifecycle-center dx-lifecycle-center — a skill for Claude Code and other platforms that manages Salesforce org connections and deploys metadata. Runs when you request environment setup or component transfers. CX Codex +1 110installs service-omni-queue-routing-config-deploy The service-omni-queue-routing-config-deploy Claude Code skill creates or updates Salesforce Omni-Channel queue routing settings. It runs for Case or Voice queue setup and when deploying a QueueRoutingConfig. CX Codex +1 108installs platform-metadata-discovery-get platform-metadata-discovery-get is a Claude Code skill that checks which Salesforce metadata already exists in an org. It runs before metadata changes or code that refers to org metadata. CX Codex +1 107installs service-omni-queue-members-assign service-omni-queue-members-assign — a Claude Code skill that assigns agent users to Salesforce queues via the Data API. Populates Case and Voice queues so Omni-Channel routing can distribute work items. CX Codex +1 106installs service-omni-skills-based-routing-configure service-omni-skills-based-routing-configure — a Claude Code skill links an Omni Skill to active agent users. It runs when setting up Omni skills-based routing. CX Codex +1 106installs service-omni-permission-set-assign service-omni-permission-set-assign — a Claude Code skill that assigns Omni permission sets to provisioned agents. It runs on requests to grant Omni-Channel access or fix permissions for the Omni widget. CX Codex +1 104installs service-omni-supervisor-config-deploy The service-omni-supervisor-config-deploy Claude Code skill deploys a classic Omni-Channel Supervisor configuration to Salesforce. It runs on requests to set up Omni Supervisor or the Supervisor Command Center. CX Codex +1 104installs

Project sponsors

Companies that keep this analytics open