forcedotcom/sf-skills/service-de-channel-activate
Claude Code and agent skill by forcedotcom/sf-skills
- community
Checking that the SKILL.md file is still in the repository.
Activate an Enhanced `MessagingChannel` (WhatsApp/Apple/Facebook/SMS/RCS) by PATCHing `MessagingChannelUsage.DeploymentStatus` from `Disabled` to `Provisioning` via the REST sobject endpoint. The UDD save-hook dispatches by `MessageType` for the external callout (`WHATS_APP`→Meta `/register`, `FACEBOOK`→`subscribeFacebookPage`, `TEXT`→`registerCsotSms`; Apple/LINE need none), writes the terminal `Active`/`Error`, and flips `IsActive`. Synchronous on the HTTP response — WhatsApp returns 204 after Meta confirms (~15-21s); no-callout channels are near-instant. No Aura RPC, no CSRF cookies. Use to activate an already-inserted Enhanced channel headlessly via REST. Do not use for full end-to-end setup — use `service-de-headless-channel-configure`.
Install
npx vskill@latest install forcedotcom/sf-skills/service-de-channel-activateSKILL.md
The same SKILL.md was published earlier as forcedotcom/sf-skills/service-de-channel-activate.
Activating a Messaging Channel
What this skill does
Given a {CHANNEL_ID}, reads the channel's MessagingChannelUsage.Id, then fires PATCH /services/data/v{V}/sobjects/MessagingChannelUsage/{MCU_ID} with body {"DeploymentStatus":"Provisioning"}. The server-side chain:
MessagingChannelUsageFunctions.validateBeforeSaverunsvalidateDeploymentStatus→validateChannelReadinessOnProvisioning. For WhatsApp this confirms consent is configured. Rejected writes return HTTP 400FIELD_INTEGRITY_EXCEPTION.MessagingChannelUsageFunctions.saveHook_PostStmtExecuteOncefires unconditionally after the UPDATE statement. It callsMessagingChannelUsageFunctionsHelper.handlePostSavewhich registers a post-commitTransactionObserver.- At commit, the observer calls
ConversationChannelUsageDeploymentStatusService.handleProvisioning(inherited fromAbstractChannelUsageDeploymentStatusService), which:
- Calls
runProvisioning—switch-dispatches byMessageTypefor the external callout: WHATS_APP→registerCsotWhatsAppNumber→LiveMessageSetupApi.registerWhatsAppNumber→ Meta/register+ status verification. 15-21s wall-clock.FACEBOOK→metaGraphApiService.subscribeFacebookPage.TEXT→registerCsotSms.AppleBusinessChat,Line, everything else →defaultbranch, no external callout, no network wait.- On success: writes
DeploymentStatus = 'Active'via PLSQL. - On failure: writes
DeploymentStatus = 'Error'plusErrorDetails(the actual cause — always read this) and a coarseErrorReasoncategory.
- Inside the same observer, a second pass syncs
MessagingChannel.IsActive = trueonce MCU reachesActive(theisTransitioningStatusflag skips the flip while status is stillProvisioning).
All synchronous within the PATCH request — the 204 response only comes back after the full chain completes. WhatsApp: ~15-21s (Meta /register round-trip). Apple / Line: ~1s (no external call; just the local save-hook + observer + PLSQL write). Verified on wadtesting 2026-04-30.
Reference File Index
| Reference file | Load when | |
|---|---|---|
references/phone-verification.md | Stage 3 comes back Error on a WhatsApp channel with ErrorDetails containing NUMBER_NOT_VERIFIED or REVERIFICATION — the phone-number OTP verification sub-flow. | |
references/worked-examples.md | You want a reference run of the WhatsApp happy-path, Apple activation, a readiness failure, or the already-active no-op. | |
references/gotchas.md | Troubleshooting an unexpected result, or before modifying this skill — the eleven known gotchas. |
Why REST PATCH instead of Apex?
A direct REST PATCH produces the identical save-hook chain as the old activateChannelUsage Apex method, with substantially less machinery — no CSRF cookie acquisition, no bootstrap fetch, no Aura response parsing, no double-wrapped returnValue. REST semantics are honest: 204 means the transition succeeded; 4xx means it didn't.
Code proof: MessagingChannelUsageFunctions.saveHook_PostStmtExecuteOnce fires on any DML path (REST, SOAP, Apex, Metadata API) — there is no Apex-specific gate. The entity XML (MessagingChannelUsage.entity.xml) marks DeploymentStatus as editAccess="always" with no <readonly> attribute. The transition validator (getValidAPIStatusTransitions) allows Disabled → Provisioning (and New → Provisioning, and Error → Provisioning | Deprovisioning, and Active → Deprovisioning). The DB-only transitions Provisioning → Active | Error are reserved for the observer's PLSQL call — that's why we write Provisioning and let the server pick the terminal state.
When NOT to use this skill
- The channel is already `IsActive=true`. Re-firing is blocked by the API transition validator (
Active → Provisioningis not ingetValidAPIStatusTransitions()) — the PATCH would return 400. The Stage 1 precondition check catches this and emitsnoop:true. - Routing isn't configured.
activateChannelUsageused to fail withLiveMessageSetupException/nullQueueIdat the Apex entry point. With the REST path the same guard lives invalidateChannelReadinessOnProvisioning— write withSessionHandlerId=null && FallbackQueueId=null→ 400FIELD_INTEGRITY_EXCEPTION. Runservice-de-channel-routing-configurefirst. The Stage 1 check still runs defensively. - The MCU doesn't exist. Can't PATCH a row that's missing. Run the insertion skill first — it always creates the MCU as a side-effect of
addChannel.
Inputs (from caller)
{CHANNEL_ID}— a 15- or 18-charMessagingChannel.Id(prefix0Mj). The channel must already exist with a non-nullSessionHandlerIdorFallbackQueueId.{ORG_ALIAS}— optional; thesfCLI target-org alias. Default: whateversf config get target-orgreturns. Used for OAuth and SOQL reads.{API_VERSION}— optional; REST API version. Default:68.0. Any version whereMessagingChannelUsageis addressable as a standard sobject is fine (v50+ should work; not exhaustively tested).
Unlike the old Aura-based version of this skill, there are no {POLL_TIMEOUT_S} / {POLL_INTERVAL_S} inputs — the PATCH is synchronous end-to-end.
Output (to caller)
Success — channel is live:
Success — no-op (already active):
Failure — precondition not met:
Failure — validator or server-side provisioning error:
Failure — auth / transport:
Stage 1: Precondition checks
Read the channel, then its MCU, as two separate SOQL calls. A combined subquery would be cheaper but fails on orgs where the child relationship is unnameable (see gotcha #4).
Let channel = /tmp/amc-precheck-channel.json records[0] and mcu = /tmp/amc-precheck-mcu.json records[0]:
| Condition | Envelope | |
|---|---|---|
| Channel query returned 0 records | {ok:false, kind:"channel-missing", hint:"MessagingChannel id not found"} | |
channel.IsActive === true | {ok:true, noop:true, channelId, message:"Channel already active"} — return | |
channel.SessionHandlerId == null && channel.FallbackQueueId == null | {ok:false, kind:"no-routing", hint:"run service-de-channel-routing-configure first"} | |
| MCU query returned 0 records | {ok:false, kind:"no-mcu", hint:"no MessagingChannelUsage row for this channel — run the insertion skill first"} | |
| Otherwise | Record {MCU_ID} = mcu.Id, {MESSAGE_TYPE} = channel.MessageType, {MESSAGING_PLATFORM_KEY} = channel.MessagingPlatformKey, {INITIAL_MCU_STATUS} = mcu.DeploymentStatus and continue to Stage 2. |
Also record {T0} (epoch ms at start of Stage 2) so the final envelope can report durationMs.
Stage 1.1: Fast path for already-provisioning MCU
If {INITIAL_MCU_STATUS} === "Provisioning" — the MCU is already mid-flight from a prior call in this transaction window. Skip Stage 2 (firing the PATCH) entirely and jump to Stage 3 (verification). This is a rare race guard: the observer is synchronous with the PATCH, so by the time the caller sees the 204 the status is already terminal (Active or Error) — Provisioning should be invisible from outside. If we do see it in the precheck, something wrote Provisioning in a separate DML and the observer is still mid-flight — don't fire a second PATCH.
Stage 2: PATCH MessagingChannelUsage.DeploymentStatus = "Provisioning"
Use sf api request rest so authentication stays inside the CLI's transport — no OAuth token is ever extracted into shell state.
Fire the PATCH. This call can take 15-30 seconds for WhatsApp — the observer runs synchronously, including Meta's /register round trip. sf api request rest has no separate client-side timeout to raise; it waits on the underlying HTTP call.
--include prints the HTTP status/headers block ahead of the (typically empty, on 204) body. Match the HTTP/x.y NNN status line itself — not head -1: with 2>&1, the CLI's Warning: @salesforce/cli update available from 2.150.6 to 2.154.4 line can come first, and a bare 3-digit grep then returns 150.
Classify by HTTP status:
| Status | Body | Handling | |
|---|---|---|---|
| 204 | empty | Success. The observer ran to completion; MCU is Active or Error. Continue to Stage 3 to read the terminal state. | |
| 400 | [{errorCode:"FIELD_INTEGRITY_EXCEPTION", message:"..."}] | Validator rejection. See table below. | |
| 400 | [{errorCode:"INVALID_FIELD_FOR_INSERT_UPDATE" or "MALFORMED_ID", ...}] | Skill bug — the MCU_ID from Stage 1 was wrong, or the body shape is off. Emit {ok:false, kind:"transport", status:400, message}. | |
| 401 | (usually empty) | Bearer token invalid. Emit {ok:false, kind:"auth", hint:"OAuth token invalid / expired — run 'sf org login web'"}. | |
| 403 | [{errorCode:"INSUFFICIENT_ACCESS"}] | User lacks perm to write DeploymentStatus. Emit {ok:false, kind:"business", errorCode:"INSUFFICIENT_ACCESS", message}. | |
| 5xx | varies | Transport. The observer may have partially committed — Stage 3's SOQL is the source of truth. Read MCU state; if it's Active, report success with a warning; if Error or still Disabled, classify as {ok:false, kind:"transport", status, message}. |
Known 400 `FIELD_INTEGRITY_EXCEPTION` messages:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/service-de-channel-activate/SKILL.md
Popularity
- Repository stars
- 1,054
- Repository forks
- 353
- 7-day trend score
- 40
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/forcedotcom/sf-skills/service-de-channel-activate)