Skip to content

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

service-de-channel-activate

Verified

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

FileKindSize
SKILL.mdskill md20.3 KB
references/gotchas.mdmarkdown7.4 KB
references/phone-verification.mdmarkdown9.0 KB
references/worked-examples.mdmarkdown909 B

references/gotchas.md

View on GitHub
---
name: service-de-channel-activate-gotchas
description: "Load when debugging an unexpected result from service-de-channel-activate, or before implementing changes to it. Covers the eleven known gotchas: synchronous PATCH timing for WhatsApp, valid API status transitions, the IsActive sync pass, relationship-name variance across orgs, consent preconditions, DeploymentStatus picklist casing, the REST-vs-Apex equivalence, the ErrorReason picklist and ErrorDetails reason format, detecting OTP verification from ErrorDetails, keeping auth inside the CLI transport (sf api request rest), and the Status-code-409 Admin API conflict. DO NOT load this during a normal first-time activation run — only when troubleshooting or modifying the skill."
metadata:
  version: "1.0"
  related-skills: service-de-channel-activate
---

# Gotchas

1. **PATCH is synchronous with Meta `/register` for WhatsApp.** Expect 15-30s response times. Don't set an HTTP client timeout below 60s. The observer runs post-commit but before the HTTP response headers ship — the 204 is the "it all worked" signal. This is why a WhatsApp channel inserted by `service-de-channel-create` takes noticeably longer to activate than an Apple or LINE channel, which have no external callout.

2. **Valid API status transitions are gated by `ChannelUsageDeploymentStatusEnum.getValidAPIStatusTransitions()`.** From `Disabled` or `New`, only `Provisioning` is allowed. From `Error`, `Provisioning` (retry) or `Deprovisioning` (give up). From `Active`, only `Deprovisioning`. The DB-only transitions (`Provisioning → Active|Error` and `Deprovisioning → Disabled`) cannot be written by a client — that's the server's job. Don't try to shortcut by PATCHing `Active` directly; the validator returns 400.

3. **The second save-hook fire that flips `IsActive` runs in the same observer, not as a separate request.** Inside `MessagingChannelUsageFunctionsHelper.handlePostSave`'s TransactionObserver, after the PLSQL status write, a second pass iterates `messagingChannelObjectsToUpdate` and flips `IsActive` via `setBypassingIsActiveGate(true)`. So one PATCH produces a fully-activated channel — no second client call needed.

4. **`MessagingChannelId` is the FK name on MCU, and the parent-to-child relationship name varies across orgs.** On `test1`, `MessagingChannel` has child relationship `MessagingChannelUsages` (plural) so `(SELECT ... FROM MessagingChannelUsages)` works. On `wadtesting`, the child relationship is `None` (unnameable) and the same subquery errors `INVALID_TYPE`. Stage 1 uses two FK-keyed queries to sidestep the variance — don't collapse them back into a subquery.

5. **Consent configuration is a precondition validator.** For WhatsApp, `validateChannelReadinessOnProvisioning` requires STOP/HELP keyword consent. If not configured, PATCH fails with `FIELD_INTEGRITY_EXCEPTION` at `validateBeforeSave` time (before the observer even runs). The old Apex method hit the same validator — this isn't a regression. If a caller sees `kind:"readiness-failed"` with a consent message, the fix is either configure consent in Setup → Messaging Settings or programmatically via `MessagingConsentConfig` — not the activation skill's concern.

6. **`DeploymentStatus` picklist values are PascalCase.** Specifically `Provisioning`, `Active`, `Error`, `Disabled`, `Deprovisioning`, `New`. Case-sensitive — `PROVISIONING` fails. The values are defined in `ChannelUsageDeploymentStatusEnum` and reflected in the sobject picklist metadata.

7. **The REST PATCH is equivalent to the old Apex `activateChannelUsage` method** but without the Aura session machinery or the quirk where that method returned `isSuccessful:false` with a misleading error even on success.

8. **On failure, read `ErrorDetails` — it is the field that says what went wrong.** The MCU lands on `Error` with `ErrorDetails` (text, truncated at 255 chars) carrying the actual cause. For Meta `/register` failures it reads `WhatsAppNumberRegistrationError__WhatsApp number registration failed <phoneId>: <REASON> (code <c>, subcode <s>) [fbtrace_id …]: <Meta message>`, where `<REASON>` is derived server-side: `NUMBER_NOT_VERIFIED` (code 100 / subcode 2593005), `REVERIFICATION` (133006), `RATE_LIMITED` (133016), `TWO_FACTOR_MISMATCH` (133005), `TWO_STEP_GUESSED_TOO_FAST` (133009), `BUSINESS_LOCKED` (131031), `DELETED_NUMBER` (33), `LOGGED_IN_ON_SMB_APP` / `DISABLE_2FA_ON_SOURCE_NUMBER` (subcode 2388001), and others. Admin API failures use the `AdminApiRegistrationError__` prefix instead (gotcha #11). Branch on `ErrorDetails`, and pass it through verbatim in the `provisioning-error` envelope. `ErrorReason` is only a coarse restricted-picklist category (`ProvisioningError`, `InternalError`, `InvalidSelection`, `DeprovisioningError`, `WHATSAPP_PROV_ERR_*` / `WHATSAPP_DEPROV_ERR_*`) — Meta registration failures are all plain `ProvisioningError`, so never branch on it; include it in the envelope for context only.

9. **The OTP-verification case is signalled in `ErrorDetails`, not `ErrorReason`.** There is no `VERIFICATION_REQUIRED` value — it isn't in the `ErrorReason` picklist, so a check on it never fires and an unverified number falls through to a generic `provisioning-error`. Trigger Stage 3.2 when a WhatsApp MCU is `Error` and `ErrorDetails` contains `NUMBER_NOT_VERIFIED` or `REVERIFICATION`; the reason token comes right after the phone id, so it survives the 255-char truncation. Observed on sdb6 (2026-10-20, channel `<channel-id>`): `ErrorReason=ProvisioningError`, `ErrorDetails=WhatsAppNumberRegistrationError__WhatsApp number registration failed <phone-id>: NUMBER_NOT_VERIFIED (code 100, subcode 2593005) [fbtrace_id …]: Phone number is not verified through sms or voice, …`. After verification, retry activation once (Stage 3.2 Step 5) — `Error → Provisioning` is a valid transition.

10. **Auth stays inside the CLI transport — use `sf api request rest`, not a manually-extracted bearer token.** The skill used to extract an OAuth token via `SF_TEMP_SHOW_SECRETS=true sf org display` + `jq -r '.result.accessToken'` and pass it as an `Authorization: Bearer` header to `curl`. That pattern put a live access token into shell state (visible in process lists, shell history, and any logging) and was removed as an S1 security anti-pattern. `sf api request rest --target-org '{ORG_ALIAS}'` manages the same OAuth session internally and never surfaces the token to the shell. Historical note: the old pattern's failure mode — omitting `SF_TEMP_SHOW_SECRETS` left the token field null, which surfaced as a 401 `INVALID_AUTH_HEADER` — no longer applies now that the CLI handles auth end-to-end.

11. **`ErrorDetails` containing "Status code = 409" comes from the *Salesforce* Admin API, not Meta.** When `ErrorReason = "ProvisioningError"` with `ErrorDetails = "AdminApiRegistrationError__Error occured in admin api with error code  and error message Channel Registration response from Admin Api is a failure. Status code = 409"`, this indicates the phone number is already registered to a *different Salesforce org*. The Salesforce Admin API enforces a global constraint: one phone number can only be registered to one org at a time. To resolve: deactivate and deregister the phone from the other org, or use a different phone number for this org. This is distinct from Meta `/register` errors, which also land as `ProvisioningError` but carry the `WhatsAppNumberRegistrationError__` prefix and a Meta code/subcode in `ErrorDetails` (gotcha #8).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated 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