Skip to content

forcedotcom/sf-skills / skills/service-de-channel-settings-configure

service-de-channel-settings-configure

Verified

Configure settings on an already-existing Enhanced `MessagingChannel` (any type — WhatsApp, Text/SMS, LINE, Apple, Facebook, EmbeddedMessaging), given its `{CHANNEL_ID}`. Covers five facets: consent (ConsentType + per-language keyword records), automated responses, messaging keywords, session-inactivity timeouts, and pre-chat parameters. Consent + a matching language-keyword record are required for activation's readiness check. TRIGGER when setting or changing settings on a channel that already exists (opt-out keyword, consent type, double opt-in confirmation, initial/help auto-responses, OptIn/OptOut keywords, session-inactivity timeout) — typically between insertion/routing and activation, or on a live channel. DO NOT TRIGGER for creating a new channel (`service-de-channel-create`), deploying a MIAW/EmbeddedMessaging channel from metadata XML (`service-digital-engagement-channel-configure`), setting routing (`service-de-channel-routing-configure`), or activating a channel (`service-de-channel-activate`).

FileKindSize
SKILL.mdskill md15.1 KB
references/channel-settings-facets.mdmarkdown7.9 KB
references/gotchas.mdmarkdown10.8 KB
references/language-keywords.mdmarkdown5.7 KB
references/worked-examples.mdmarkdown6.2 KB

references/gotchas.md

View on GitHub
---
name: service-de-channel-settings-configure-gotchas
description: "Load when debugging an unexpected result from service-de-channel-settings-configure, or before implementing changes to it. Covers the known gotchas: the exact per-ConsentType activation-readiness contract and its source, the ImplicitOptIn-still-needs-a-keyword-record trap, comma-separated keyword storage, one-record-per-language uniqueness, the Unified-SMS help/French-custom rules, the OptInPrompt Unified-SMS/WhatsApp/RCS exemption, the outbound-only auto-pass, the Enhanced-only gate, the legacy OptInResponse/OptOutResponse deprecation, why MsgChannelLanguageKeyword must be written over the Data/SObjects API rather than the Tooling API despite its setupEntity perApiAccess block, which inactivity fields deploy on 262 vs 264 pods, and the Facebook metadata-update failure. DO NOT load this during a normal first-time consent run — only when troubleshooting or modifying the skill."
metadata:
  version: "1.0"
  related-skills: service-de-channel-settings-configure
---

# Gotchas

1. **The activation-readiness contract lives in `MessagingChannelReadinessChecker.isConsentConfiguredForChannel`.** This is the authority — the UI (`channelRecordHome.js`, `languageOptionsModal.js`) mirrors it but is advisory. The three validators are:
   - `checkIfChannelIsConfiguredForImplicitOptIn`: at least one `MsgChannelLanguageKeyword` with `OptOutKeywords != null && OptOutConfirmation != null`.
   - `checkIfChannelIsConfiguredForExplicitOptIn`: implicit rule **plus** `OptInKeywords != null`, **plus** on the channel `(OptInPrompt != null || isUnifiedSMSOrWhatsappOrRCS)`.
   - `checkIfChannelIsConfiguredForDoubleOptIn`: explicit rule **plus** `DoubleOptInKeywords != null`, **plus** on the channel `DoubleOptInPrompt != null`.
   Consent is ANDed with routing in `isChannelReadyForActivation` — a channel with perfect routing still fails activation if consent is unmet.

2. **ImplicitOptIn is NOT a no-op.** The common misconception is that "implicit" means "nothing to configure." It still requires a `MsgChannelLanguageKeyword` record with opt-out keyword + opt-out confirmation. A channel set to `ConsentType=ImplicitOptIn` with zero keyword records fails the readiness check. This is the single most likely reason a freshly-configured channel won't activate.

3. **Outbound-only channels pass consent automatically.** `isOutboundOnlyChannel` short-circuits `isConsentConfiguredForChannel` to true. Don't try to configure consent on an outbound-only channel — there's nothing to satisfy, and the skill's "When NOT to use" section bails on this case.

4. **Keywords are comma-separated strings, not picklists.** Store `OptOutKeywords` as `STOP,UNSUBSCRIBE,CANCEL`. The server splits on comma and trims. A JSON array or newline-separated value will not match correctly. See `references/language-keywords.md`.

5. **One `MsgChannelLanguageKeyword` record per (channel, language).** Don't create a second record for a language that already has one — PATCH the existing record. Duplicate language records are ambiguous for the readiness check (it only needs *one* satisfying record, but duplicates make the UI and future edits inconsistent).

6. **`OptInPrompt` is exempt from the readiness check on Unified SMS / WhatsApp / RCS.** `isUnifiedSMSOrWhatsappOrRCS` makes `OptInPrompt` optional for the ExplicitOptIn/DoubleOptIn readiness rule. For all other channel types, `OptInPrompt` is required for ExplicitOptIn and DoubleOptIn. Note: `DoubleOptInPrompt` has NO such exemption — it is always required for DoubleOptIn regardless of channel type. **Detecting the exemption from a query:** there is no `IsUnifiedMessagingEnabled` column on the Data-API `MessagingChannel` sObject (verified via `sf sobject describe` on sdb6c 2026-08-13 — the queryable surface is `MessageType`, `PlatformType`, `MessagingPlatformKey`). Use `PlatformType='Enhanced' AND MessageType IN ('Text','WhatsApp','Rcs')` as the proxy for `isUnifiedSMSOrWhatsappOrRCS`. `MessageType` picklist values on this org include `Text`, `WhatsApp`, `Rcs`, `Facebook`, `AppleBusinessChat`, `EmbeddedMessaging`, `Line`, etc.

7. **Unified SMS adds two mandatory keyword-record rules.** Only when the channel is Unified SMS: `HelpKeywords`+`HelpResponse` become mandatory, and a `fr_CA` record additionally needs `CustomKeywords`+`CustomResponse`. These are enforced by the readiness check for Unified SMS and are irrelevant (optional) on WhatsApp/Facebook/etc.

8. **Consent applies to Enhanced channels only.** The UI gates the consent panel with `consentSettingsEnabled = platformType === 'Enhanced' && supportedMessageTypes.includes(messageType)`. On a Standard channel these fields are unused. Stage 1 confirms `PlatformType=Enhanced` and emits `kind:"not-enhanced"` otherwise.

9. **Legacy `OptInResponse` / `OptOutResponse` on `MessagingChannel` are deprecated (API 224).** Do NOT write them — the modern surface is `ConsentType` + `OptInPrompt` + `DoubleOptInPrompt` on the channel, and the per-language responses on `MsgChannelLanguageKeyword` (`OptInConfirmation`/`OptOutConfirmation`). The readiness check does not read the legacy fields.

10. **Switching ConsentType down should null the now-unused prompts.** The UI nulls `OptInPrompt` and `DoubleOptInPrompt` when moving to ImplicitOptIn, and nulls `DoubleOptInPrompt` when moving to ExplicitOptIn. If you re-run this skill to *lower* a channel's consent level, follow the same discipline so stale prompt text doesn't linger — though leaving them set does not fail the readiness check, it misrepresents the channel's configuration.

11. **WhatsApp channels with rich content reject `ExplicitOptIn`.** Setting `ConsentType=ExplicitOptIn` on a WhatsApp channel that has rich content is rejected server-side with `INVALID_INPUT: Consent Type for WhatsApp Messaging Channel with rich content cannot be set to EXPLICIT_OPT_IN` (verified live on sdb6c 2026-08-13). WhatsApp rich-content channels are effectively `ImplicitOptIn`. If the user asks for ExplicitOptIn/DoubleOptIn on such a channel, surface this constraint rather than retrying — emit `kind:"channel-patch-failed"` with the server message. Not all message types accept all ConsentTypes; the server is the authority.

12. **The `sf data ... --values` quoting rule is load-bearing.** The CLI tokenizes `--values` on spaces, so every multi-word value (all prompts, all confirmation messages) must be single-quoted *inside* the double-quoted `--values` string: `OptInPrompt='Reply YES to receive messages'`. Unquoted, it fails before hitting the server with `Malformed key=value pair for value: <second word>` (verified live). Keyword CSVs without spaces (`OptOutKeywords=stop,unsubscribe`) don't need quoting. To null a prompt when down-switching ConsentType, pass `OptInPrompt=''` — verified to set the field to null.

13. **`ConsentType` requires minApiVersion 224.** All consent fields (`ConsentType`, `OptInPrompt`, `DoubleOptInPrompt`, `IsRequireDoubleOptIn`) and the `MsgChannelLanguageKeyword` entity were introduced in API 224. The skill declares `minApiVersion: "67.0"` (well above 224); on an older org the fields won't exist and the Stage 1 query will error.

14. **Write `MsgChannelLanguageKeyword` over the regular Data/SObjects API — NOT the Tooling API.** `sf data create/update record --sobject MsgChannelLanguageKeyword` (the path this skill uses) works and is the sanctioned write path — verified live on sdb6c 2026-08-13: a `sf data update record` returned `success=true` at API v69.0, and `sf sobject describe` reports the object `createable: true, updateable: true`. **The entity XML is misleading here.** `MsgChannelLanguageKeyword.entity.xml` is a `setupEntity` carrying `<perApiAccess minApiVersion="246" apiAccess="isDevInternal || isUiTier" sobjectFamily="TOOLING"/>`. That block reads like a blanket write gate, but `sobjectFamily="TOOLING"` scopes it to the **Tooling API family only** — `ApiDictionaryInitializer._getFieldAccessStrategy` selects the `TOOLING` `perApiAccess` seed exclusively when `apiFamily.isTooling()`, so a regular SObjects/Data API request never applies it and instead uses the entity's base `createAccess`/`editAccess` (`LiveMessage.userCanCustomizeSetup`, which a setup-capable admin satisfies). Consequently a **Tooling** API write (`sf ... --use-tooling-api`, or the Tooling REST/SOAP endpoints) returns `NOT_FOUND` for this entity for external callers, while the Data API write succeeds. If a keyword write fails, first suspect a transient org issue (sdb6c 503 maintenance windows produced spurious `UNKNOWN_EXCEPTION` on Data-API writes during testing) and retry — do NOT switch to the Tooling API thinking it's the "real" write path; it isn't.

15. **Inactivity fields are release-gated: 262 vs 264.** The Metadata API only exposes all four facet-4 fields from release **264**. The Setup UI can set all of them on 262 because it writes through a different layer. Check the org's release (`sf org display` → API version: v67.0 = 262, v69.0 = 264) before promising the full set:
   | Field | 262 pods | 264+ |
   | --- | --- | --- |
   | `endUserIdleTimeOut` | deploys and persists | deploys and persists |
   | `endUserIdleAction` | **rejected** by the deploy schema | deploys and persists |
   | `endInactiveSessionTimeOut` | **rejected** by the deploy schema | deploys and persists |
   | `isAgentMessageResetInactivityEnabled` | deploy reports `Succeeded` but the field is **silently dropped** | deploys and persists |
   No org setting turns these on; only a 264+ build has them. On 262, deploy only `endUserIdleTimeOut` and report the other three as unsupported on this release. The Stage 5 re-retrieve is what catches the silent drop of the reset flag — never trust a `Succeeded` deploy on its own. The 5–30 minute bound on `endUserIdleTimeOut` is enforced server-side on both (`must be between 5 and 30 minutes`; the org value is unchanged). (Verified on a v67.0/262 org and a v69.0/264 org, Round 4/5 validation, 2026-10.)

16. **Facebook channels reject any real metadata change with an opaque numeric error.** Deploying an edited `.messagingChannel-meta.xml` for a Facebook channel fails with a bare code like `(-462367322)`, even when the only change is `masterLabel`. Redeploying the unchanged retrieved file succeeds, but only because nothing changed. It reproduces on a brand-new, correctly configured Facebook channel on a 264 org (2026-10), so it isn't corruption of one channel; the root cause is unknown and looks like a platform defect. MIAW channels on the same org deploy fine. Until it's fixed, facets 2–4 can't be written headlessly on Facebook: don't retry. Emit `{ok:false, kind:"metadata-deploy-failed", message:"<the code>", hint:"Facebook channels currently reject metadata updates with this opaque error (known platform issue, not your input). Configure these settings in Setup → Messaging Settings → this channel instead."}`. Consent (facet 1, Data API) is unaffected.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated 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