forcedotcom/sf-skills/service-de-channel-activate

Claude Code and agent skill by forcedotcom/sf-skills

Trust tier 2
  • community
LLM review pending
Source check pending

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-activate

SKILL.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:

  1. MessagingChannelUsageFunctions.validateBeforeSave runs validateDeploymentStatus → validateChannelReadinessOnProvisioning. For WhatsApp this confirms consent is configured. Rejected writes return HTTP 400 FIELD_INTEGRITY_EXCEPTION.
  2. MessagingChannelUsageFunctions.saveHook_PostStmtExecuteOnce fires unconditionally after the UPDATE statement. It calls MessagingChannelUsageFunctionsHelper.handlePostSave which registers a post-commit TransactionObserver.
  3. At commit, the observer calls ConversationChannelUsageDeploymentStatusService.handleProvisioning (inherited from AbstractChannelUsageDeploymentStatusService), which:
  • Calls runProvisioning — switch-dispatches by MessageType for 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 → default branch, no external callout, no network wait.
  • On success: writes DeploymentStatus = 'Active' via PLSQL.
  • On failure: writes DeploymentStatus = 'Error' plus ErrorDetails (the actual cause — always read this) and a coarse ErrorReason category.
  1. Inside the same observer, a second pass syncs MessagingChannel.IsActive = true once MCU reaches Active (the isTransitioningStatus flag skips the flip while status is still Provisioning).

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 fileLoad when
references/phone-verification.mdStage 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.mdYou want a reference run of the WhatsApp happy-path, Apple activation, a readiness failure, or the already-active no-op.
references/gotchas.mdTroubleshooting 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 → Provisioning is not in getValidAPIStatusTransitions()) — the PATCH would return 400. The Stage 1 precondition check catches this and emits noop:true.
  • Routing isn't configured. activateChannelUsage used to fail with LiveMessageSetupException / nullQueueId at the Apex entry point. With the REST path the same guard lives in validateChannelReadinessOnProvisioning — write with SessionHandlerId=null && FallbackQueueId=null → 400 FIELD_INTEGRITY_EXCEPTION. Run service-de-channel-routing-configure first. 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-char MessagingChannel.Id (prefix 0Mj). The channel must already exist with a non-null SessionHandlerId or FallbackQueueId.
  • {ORG_ALIAS} — optional; the sf CLI target-org alias. Default: whatever sf config get target-org returns. Used for OAuth and SOQL reads.
  • {API_VERSION} — optional; REST API version. Default: 68.0. Any version where MessagingChannelUsage is 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:

json
{"ok": true, "channelId": "0Mj...", "mcuId": "0gL...", "deploymentStatus": "Active", "isActive": true, "messageType": "WhatsApp", "durationMs": 20934}

Success — no-op (already active):

json
{"ok": true, "noop": true, "channelId": "0Mj...", "message": "Channel already active"}

Failure — precondition not met:

json
{"ok": false, "kind": "no-routing", "hint": "run service-de-channel-routing-configure first"}
{"ok": false, "kind": "no-mcu", "hint": "no MessagingChannelUsage row for this channel — run the insertion skill first"}
{"ok": false, "kind": "channel-missing","hint": "MessagingChannel id not found"}

Failure — validator or server-side provisioning error:

json
{"ok": false, "kind": "readiness-failed", "errorCode": "FIELD_INTEGRITY_EXCEPTION",
"message": "...", "hint": "validateChannelReadinessOnProvisioning rejected the write — most commonly missing consent; run service-de-channel-settings-configure first"}
{"ok": false, "kind": "provisioning-error", "mcuId": "0gL...", "errorReason": "ProvisioningError", "errorDetails": "WhatsAppNumberRegistrationError__..."}
{"ok": false, "kind": "verification-failed", "hint": "WhatsApp phone number verification failed or was declined by user"}
{"ok": false, "kind": "verification-request-failed", "errorCode": "...", "message": "...", "hint": "Could not request verification code from Meta"}

Failure — auth / transport:

json
{"ok": false, "kind": "auth", "hint": "OAuth token invalid / expired — run 'sf org login web'"}
{"ok": false, "kind": "transport", "status": 500, "message": "..."}

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).

bash
sf data query --target-org '{ORG_ALIAS}' \
--query "SELECT Id, DeveloperName, MessageType, IsActive, SessionHandlerId, FallbackQueueId, MessagingPlatformKey FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
--json > /tmp/amc-precheck-channel.json
sf data query --target-org '{ORG_ALIAS}' \
--query "SELECT Id, DeploymentStatus, DeploymentType, ErrorReason, ErrorDetails FROM MessagingChannelUsage WHERE MessagingChannelId = '{CHANNEL_ID}'" \
--json > /tmp/amc-precheck-mcu.json

Let channel = /tmp/amc-precheck-channel.json records[0] and mcu = /tmp/amc-precheck-mcu.json records[0]:

ConditionEnvelope
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"}
OtherwiseRecord {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.

bash
sf api request rest \
"/services/data/v{API_VERSION}/sobjects/MessagingChannelUsage/{MCU_ID}" \
--method PATCH \
--target-org '{ORG_ALIAS}' \
--header 'Content-Type: application/json' \
--body '{"DeploymentStatus":"Provisioning"}' \
--include \
> /tmp/amc-patch-response.txt 2>&1
HTTP_CODE=$(grep -m1 -oE '^HTTP/[0-9.]+ [0-9]{3}' /tmp/amc-patch-response.txt | awk '{print $2}')

--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:

StatusBodyHandling
204emptySuccess. 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}.
5xxvariesTransport. 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/forcedotcom/sf-skills/service-de-channel-activate/badge)](https://verified-skill.com/skills/forcedotcom/sf-skills/service-de-channel-activate)

Something wrong with this skill or its page? Tell us.