@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-de-channel-activate/references/gotchas.md

@@ -0,0 +1,31 @@
+---
+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, ErrorReason values, VERIFICATION_REQUIRED handling, 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. **If the observer fails partway, the MCU can land on `Error` with `ErrorReason` populated.** Common values for WhatsApp: `ProvisioningError` (Salesforce Admin API rejected — typically "Status code = 409" means phone already registered to another org; see gotcha #11), `MetaRegistrationFailed` (Meta `/register` rejected the phone — could be rate limit, PIN not set, WABA not shared, or credit line not attached), `NotAuthorized` (WABA partnership hasn't propagated). The `ErrorDetails` column carries the raw error response (Salesforce Admin API or Meta Graph API depending on where it failed). Don't swallow these — pass through to the caller's `provisioning-error` envelope.
+
+9. **`ErrorReason === "VERIFICATION_REQUIRED"` means phone number needs OTP verification.** When activation fails with this specific ErrorReason on the MessagingChannelUsage, the skill should automatically proceed to Stage 3.2 (WhatsApp verification flow) rather than returning a generic provisioning-error. This is a recoverable error state that we can handle programmatically via the Connect REST verification endpoints. After successful verification, retry activation once (Stage 3.2 Step 5). Live-validated on headless-sdb6 2026-05-21 — verification request → SMS code entry → validation → retry activation succeeded in ~1 minute total.
+
+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's validation errors (which would appear with `ErrorReason = "MetaRegistrationFailed"` and carry Meta Graph API error codes in `ErrorDetails`).

package/skills/service-de-channel-activate/references/phone-verification.md

@@ -0,0 +1,96 @@
+---
+name: service-de-channel-activate-phone-verification
+description: "Load when service-de-channel-activate's Stage 3 read comes back with MessagingChannelUsage.ErrorReason === \"VERIFICATION_REQUIRED\" (WhatsApp channels only). Covers the phone-number OTP verification sub-flow: prompting for SMS/voice, requesting and validating the verification code via the Connect livemessage/whatsapp/verification endpoints, and retrying activation once verification succeeds. DO NOT load this for any other ErrorReason, for non-WhatsApp message types, or during the normal happy-path activation run."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-activate
+---
+
+# Stage 3.2: WhatsApp phone number verification (only if ErrorReason === "VERIFICATION_REQUIRED")
+
+**This stage only runs for WhatsApp channels when activation fails with `VERIFICATION_REQUIRED`.** The phone number must be verified with Meta before it can be registered. We use the two Connect REST verification endpoints via `sf api request rest`, which manages OAuth internally — no token extraction needed.
+
+#### Step 1: Prompt for verification method
+
+Ask the user:
+
+```text
+WhatsApp phone number verification required.
+
+How should we send the verification code?
+
+  [1] SMS (text message)
+  [2] Voice call
+
+Choice [1/2]:
+```
+
+Record `{CODE_METHOD}` as `"SMS"` or `"VOICE"` based on response.
+
+#### Step 2: Request verification code
+
+```bash
+sf api request rest \
+  "/services/data/v{API_VERSION}/connect/livemessage/whatsapp/verification/request?numberId={PHONE_NUMBER_ID}&codeMethod={CODE_METHOD}" \
+  --method POST \
+  --target-org '{ORG_ALIAS}' \
+  --header 'Accept: application/json' \
+  --body '{}' \
+  --include \
+  > /tmp/amc-verify-request.txt 2>&1
+```
+
+`{PHONE_NUMBER_ID}` is `{MESSAGING_PLATFORM_KEY}` from Stage 1. `--include` prints the HTTP status/headers block ahead of the body — read the status from that block rather than a trailing marker line.
+
+**Important:** The endpoint expects query parameters, not a JSON body. Pass `numberId` and `codeMethod` as URL parameters. Still send `--body '{}'` (not `--body ''`): `sf api request rest` treats an empty body string as no body and fails locally with `No 'mode' found in 'body' entry` before the request is issued, so an empty `{}` object is the way to make a body-less POST reach the endpoint.
+
+| HTTP status | Body | Handling |
+| --- | --- | --- |
+| 200 or 204 | Empty or `{"success": true, "displayNumber": "..."}` | Success. Continue to Step 3. Optionally extract `displayNumber` from response to show user which phone will receive the code. |
+| 400 | `[{errorCode: "...", message: "..."}]` | Business error. Common: code already requested recently (Meta rate limit). Emit `{ok:false, kind:"verification-request-failed", errorCode, message, hint:"Meta may be rate-limiting requests. Wait a few minutes and retry."}`. |
+| 401 | (empty) | Bearer token invalid. Emit `{ok:false, kind:"auth"}`. |
+| 404 | HTML | Endpoint unavailable. Emit `{ok:false, kind:"transport", status:404, hint:"Verification endpoint not available — check API version"}`. |
+
+#### Step 3: Prompt for verification code
+
+```text
+A {CODE_METHOD} verification code has been sent to the phone number.
+Please check the device and enter the 6-digit code:
+
+Code: 
+```
+
+Read user input, trim whitespace, **remove any hyphens**, record as `{VERIFICATION_CODE}`. Must be exactly 6 digits after hyphen removal. Users often enter codes like `123-456`; we must strip the hyphen and send `123456` in the request body.
+
+#### Step 4: Validate verification code
+
+```bash
+sf api request rest \
+  "/services/data/v{API_VERSION}/connect/livemessage/whatsapp/verification/validate?numberId={PHONE_NUMBER_ID}&verificationCode={VERIFICATION_CODE}" \
+  --method POST \
+  --target-org '{ORG_ALIAS}' \
+  --header 'Accept: application/json' \
+  --body '{}' \
+  --include \
+  > /tmp/amc-verify-validate.txt 2>&1
+```
+
+**Important:** The endpoint expects query parameters, not a JSON body. Pass `numberId` and `verificationCode` as URL parameters. Send `--body '{}'` rather than `--body ''` — an empty body string makes `sf api request rest` fail locally with `No 'mode' found in 'body' entry` before the POST is sent.
+
+| HTTP status | Body | Handling |
+| --- | --- | --- |
+| 200 or 204 | Empty or `{"success": true}` | Success. Number is now verified. Continue to Step 5 (retry activation). |
+| 400 | `[{errorCode: "...", message: "..."}]` | Invalid code or rate limit. Parse error message: if "wrong code" or "guessing too fast", prompt: "Invalid verification code. Try again? [y/n]". If `y`, repeat Step 3 (up to 3 total attempts). If `n` or after 3 failures, emit `{ok:false, kind:"verification-failed", hint:"Verification code validation failed"}`. |
+| 401 | (empty) | Bearer token invalid. Emit `{ok:false, kind:"auth"}`. |
+
+Common Meta error codes from the UI component:
+- `136024`: Too many recent attempts (rate limit). Emit `{ok:false, kind:"verification-failed", hint:"Too many verification attempts. Wait a few minutes and retry activation."}`.
+- `136025`: Wrong code or guessing too fast. Allow retry (up to 3 attempts total).
+
+#### Step 5: Retry activation after verification
+
+The phone number is now verified. Return to Stage 2 (PATCH activation) with a retry counter to avoid infinite loops. Maximum 1 retry after verification.
+
+If the second activation attempt also fails with `VERIFICATION_REQUIRED`, emit `{ok:false, kind:"verification-failed", hint:"Phone number verification succeeded but activation still reports VERIFICATION_REQUIRED — unusual, check Meta Business Manager"}`.
+
+If the second activation succeeds (`Active`), proceed to Stage 4 as normal.

package/skills/service-de-channel-activate/references/worked-examples.md

@@ -0,0 +1,14 @@
+---
+name: service-de-channel-activate-worked-examples
+description: "Load when you want a reference run of service-de-channel-activate's activation flow — a full end-to-end trace for a given path or failure mode. Covers WhatsApp activation via REST PATCH (the reference happy-path), Apple Business Chat activation, a readiness-validator failure (missing consent), and an already-active no-op. DO NOT load this during normal execution of the skill's stages — only when a concrete trace is wanted for reference or debugging."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-activate
+---
+
+# Worked examples: `service-de-channel-activate`
+
+- WhatsApp activation on wadtesting via REST PATCH (verified 2026-04-30 — the reference happy-path, ~21s wall-clock)
+- Apple Business Chat activation (sub-second, no external call)
+- Readiness-validator failure (missing consent)
+- Already-active no-op

package/skills/service-de-channel-consent-configure/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: service-de-channel-consent-configure
+description: "Configure consent (opt-in/opt-out) on an Enhanced `MessagingChannel` so activation will accept it. Given a `{CHANNEL_ID}`, sets the channel's `ConsentType` (ImplicitOptIn / ExplicitOptIn / DoubleOptIn) and the `OptInPrompt` / `DoubleOptInPrompt` prompt fields, then creates or updates one `MsgChannelLanguageKeyword` record per language holding the opt-in / double-opt-in / opt-out / help / custom keywords and confirmation messages. Use between channel insertion and activation — activation fails the consent-readiness check unless a valid ConsentType and at least one matching language-keyword record exist."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "service-de-channel-activate"
+    - "service-de-channel-routing-configure"
+    - "service-de-headless-channel-configure"
+---
+
+# Configuring Channel Consent
+
+## What this skill does
+
+Ensures an Enhanced `MessagingChannel` has valid **consent** configured before activation. Consent has two parts, and both are checked by the server-side activation-readiness gate (`MessagingChannelReadinessChecker.isConsentConfiguredForChannel`):
+
+1. **Channel-level fields** on `MessagingChannel`:
+   - `ConsentType` — static enum: `ImplicitOptIn`, `ExplicitOptIn`, or `DoubleOptIn`.
+   - `OptInPrompt` — message sent when an end-user reply doesn't match an opt-in keyword (required for ExplicitOptIn/DoubleOptIn, except on Unified SMS / WhatsApp / RCS where it's optional).
+   - `DoubleOptInPrompt` — message sent when a reply doesn't match a double-opt-in keyword (required for DoubleOptIn).
+   - `IsRequireDoubleOptIn` — boolean flag; set true alongside `ConsentType=DoubleOptIn`.
+
+2. **Per-language keyword records** — one or more `MsgChannelLanguageKeyword` child rows (master-detail to `MessagingChannel`, key prefix `3Or`). Each holds the keywords an end-user sends (opt-in, double-opt-in, opt-out, help, custom) and the confirmation replies, **for one language**. Keyword fields are **comma-separated strings** (e.g. `"STOP,UNSUBSCRIBE,CANCEL"`).
+
+**Consent is never a no-op for activation.** Even `ImplicitOptIn` requires at least one `MsgChannelLanguageKeyword` with an opt-out keyword + opt-out confirmation. (The one exception is an outbound-only channel, which the readiness check passes automatically.)
+
+Consent settings apply only to **Enhanced** channels (`PlatformType=Enhanced`) of a supported message type. On a Standard channel these fields aren't used; this skill only touches Enhanced channels.
+
+## Where this fits
+
+This skill runs between routing and activation in the Enhanced-channel setup pipeline. `service-de-channel-routing-configure` sets the channel's `SessionHandler`; this skill configures consent; then `service-de-channel-activate` flips the channel live. The activation readiness check requires **both** routing and consent, so run this before activating. The `service-de-headless-channel-configure` orchestrator sequences all three automatically — invoke this skill directly only when you want to configure consent on its own.
+
+## Reference File Index
+
+| Reference file | Load when |
+| --- | --- |
+| `references/language-keywords.md` | Creating or updating the per-language `MsgChannelLanguageKeyword` records — full field list, CSV keyword semantics, create-vs-update logic, and the Unified-SMS help/custom-keyword rules. |
+| `references/gotchas.md` | Troubleshooting an unexpected result, or before modifying this skill. |
+| `references/worked-examples.md` | You want a reference run of the ImplicitOptIn, ExplicitOptIn, or DoubleOptIn paths. |
+
+## When NOT to use this skill
+
+- **The channel isn't Enhanced.** Consent fields apply to Enhanced channels only. This skill confirms `PlatformType=Enhanced` and stops otherwise.
+- **The channel is outbound-only.** Outbound-only channels pass the consent-readiness check automatically; there's nothing to configure.
+- **The channel doesn't exist yet.** Run the insertion skill first; this skill expects a real `MessagingChannel.Id`.
+
+## Inputs (from caller)
+
+- `{CHANNEL_ID}` — a 15- or 18-char `MessagingChannel.Id` (prefix `0Mj`). Must already exist and be Enhanced.
+- `{CONSENT_TYPE}` — optional; one of `ImplicitOptIn` | `ExplicitOptIn` | `DoubleOptIn`. If omitted, the skill prompts.
+- `{LANGUAGE}` — optional; the `MasterLanguage` for the keyword record (e.g. `en_US`). Defaults to `en_US` if not provided.
+- `{ORG_ALIAS}` — optional; `sf` CLI target-org alias. Default: whatever `sf config get target-org` returns.
+
+The individual keyword/confirmation/prompt values are collected interactively in Stage 3–4 (or accepted from the caller if pre-supplied).
+
+## Output (to caller)
+
+**Success — no change needed:**
+```json
+{"ok": true, "noop": true, "consentType": "ImplicitOptIn|ExplicitOptIn|DoubleOptIn", "languageKeywordIds": ["3Or..."], "message": "Consent already configured and activation-ready"}
+```
+
+**Success — consent configured:**
+```json
+{"ok": true, "consentType": "ExplicitOptIn", "channelFieldsSet": ["ConsentType","OptInPrompt"],
+ "languageKeywordId": "3Or...", "language": "en_US", "created": true|false, "activationReady": true}
+```
+
+**Precondition / validation not met:**
+```json
+{"ok": false, "kind": "not-enhanced", "hint": "consent fields apply to Enhanced channels only; this channel is PlatformType=<x>"}
+{"ok": false, "kind": "missing-consent-input", "hint": "<which required keyword/prompt for the chosen ConsentType is missing>"}
+```
+
+**Failure:**
+```json
+{"ok": false, "kind": "channel-patch-failed", "message": "..."}
+{"ok": false, "kind": "keyword-record-failed", "message": "..."}
+{"ok": false, "kind": "verify-failed", "hint": "writes returned success but a re-read shows the channel is still not consent-ready"}
+```
+
+---
+
+## Stage 1: Read current consent state
+
+Read the channel's consent fields and any existing language-keyword records.
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, PlatformType, MessageType, MessagingPlatformKey, ConsentType, OptInPrompt, DoubleOptInPrompt, IsRequireDoubleOptIn FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
+  --json > /tmp/cc-channel.json
+
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, MasterLanguage, OptInKeywords, DoubleOptInKeywords, OptInConfirmation, OptOutKeywords, OptOutConfirmation, HelpKeywords, HelpResponse, CustomKeywords, CustomResponse FROM MsgChannelLanguageKeyword WHERE MessagingChannelId = '{CHANNEL_ID}'" \
+  --json > /tmp/cc-keywords.json
+```
+
+If the channel record is missing — halt with `Error: Channel {CHANNEL_ID} not found — check the id, or run the insertion skill first.`
+
+If `PlatformType != 'Enhanced'` — emit `{ok:false, kind:"not-enhanced", ...}` and stop.
+
+**No-op check:** if `ConsentType` is non-null AND the existing language-keyword records already satisfy the readiness matrix for that ConsentType (see Stage 5), emit the `noop:true` envelope and return. Don't re-prompt or overwrite a channel that is already activation-ready.
+
+---
+
+## Stage 2: Choose the ConsentType
+
+If `{CONSENT_TYPE}` wasn't supplied, prompt (do NOT auto-pick):
+
+```text
+Channel '{developerName}' ({CHANNEL_ID}) — choose a consent model:
+
+  1) ImplicitOptIn  — end users are opted in by default; you only handle opt-OUT (STOP) keywords.
+  2) ExplicitOptIn  — end users must send an opt-in keyword before you can message them.
+  3) DoubleOptIn    — explicit opt-in plus a second confirming keyword.
+
+Pick [1-3]:
+```
+
+Record `{CONSENT_TYPE}`. Note the field checks that follow (this is the exact server-side activation-readiness contract — see `references/gotchas.md` for the source):
+
+| ConsentType | MessagingChannel fields | `MsgChannelLanguageKeyword` (≥1 record) |
+| --- | --- | --- |
+| ImplicitOptIn | (none required) | `OptOutKeywords` + `OptOutConfirmation` |
+| ExplicitOptIn | `OptInPrompt`¹ | above + `OptInKeywords` |
+| DoubleOptIn | `OptInPrompt`¹ + `DoubleOptInPrompt` + `IsRequireDoubleOptIn=true` | above + `DoubleOptInKeywords` |
+
+¹ `OptInPrompt` is optional (not required for readiness) on Unified SMS / WhatsApp / RCS channels — detect via `MessageType IN ('Text','WhatsApp','Rcs')` on an Enhanced channel (the queryable proxy for the server's `isUnifiedSMSOrWhatsappOrRCS`). Still recommend setting it for a good end-user experience.
+
+---
+
+## Stage 3: Collect channel-level prompt values
+
+Only prompt for the fields the chosen ConsentType requires (see the matrix above). Skip this stage entirely for `ImplicitOptIn` — it needs no channel-level prompt fields.
+
+For `ExplicitOptIn` / `DoubleOptIn`:
+
+```text
+Opt-in prompt (sent when a reply doesn't match an opt-in keyword):
+```
+For `DoubleOptIn`, also:
+```text
+Double-opt-in prompt (sent when a reply doesn't match a double-opt-in keyword):
+```
+
+Trim whitespace. If a required prompt is empty after trimming, re-prompt once; on a second empty, emit `{ok:false, kind:"missing-consent-input", hint:"..."}`.
+
+---
+
+## Stage 4: Configure the per-language keyword record
+
+Collect the keyword lists and confirmation replies for `{LANGUAGE}` (default `en_US`), then create or update the `MsgChannelLanguageKeyword` record.
+
+**Load `references/language-keywords.md` and follow it** — it holds the full field list, the comma-separated-keyword semantics, the create-vs-update decision (reuse an existing record for the same language rather than duplicating), and the Unified-SMS help/custom-keyword rules.
+
+The minimum per ConsentType (again, from the readiness contract):
+- **ImplicitOptIn:** `OptOutKeywords` (e.g. `STOP,UNSUBSCRIBE`) + `OptOutConfirmation`.
+- **ExplicitOptIn:** the above + `OptInKeywords` (e.g. `START,YES`).
+- **DoubleOptIn:** the above + `DoubleOptInKeywords` (e.g. `CONFIRM`).
+
+`OptInConfirmation`, `HelpKeywords`/`HelpResponse`, and `CustomKeywords`/`CustomResponse` are optional for the base readiness check (help/custom are only *required* on Unified SMS — see the reference), but collect them if the user wants them.
+
+---
+
+## Stage 5: Write channel fields + keyword record
+
+Write the channel-level fields in one PATCH (only the fields the ConsentType requires).
+
+**Quoting rule (load-bearing):** `sf data update record --values` splits on spaces, so any value containing a space **must be wrapped in single quotes inside the double-quoted `--values` string** — e.g. `OptInPrompt='Reply YES to receive messages'`. An unquoted `OptInPrompt=Reply YES ...` fails with `Malformed key=value pair` (verified live on sdb6c). Prompts almost always contain spaces, so always quote them.
+
+```bash
+# ImplicitOptIn — ConsentType only
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' --values "ConsentType=ImplicitOptIn" --json > /tmp/cc-patch.json
+
+# ExplicitOptIn
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' --values "ConsentType=ExplicitOptIn OptInPrompt='{OPT_IN_PROMPT}'" --json > /tmp/cc-patch.json
+
+# DoubleOptIn
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' \
+  --values "ConsentType=DoubleOptIn OptInPrompt='{OPT_IN_PROMPT}' DoubleOptInPrompt='{DBL_PROMPT}' IsRequireDoubleOptIn=true" --json > /tmp/cc-patch.json
+```
+
+If `status !== 0`: emit `{ok:false, kind:"channel-patch-failed", message: ...}` and return.
+
+Then create or update the `MsgChannelLanguageKeyword` record per `references/language-keywords.md`. If it fails: `{ok:false, kind:"keyword-record-failed", message: ...}`.
+
+---
+
+## Stage 6: Verify activation readiness
+
+Re-read both the channel and its keyword records (same two queries as Stage 1). Confirm, per the chosen ConsentType's row in the Stage 2 matrix, that every required field is now non-null on the channel AND on at least one keyword record for the configured language.
+
+If any required field is still null: emit `{ok:false, kind:"verify-failed", hint:"<which requirement is unmet>"}`.
+
+Otherwise emit the success envelope with `activationReady: true`.
+
+---
+
+## Stage 7: Report to caller
+
+Report the JSON envelope. If this skill is the leaf (user invoked it directly), render:
+
+- `Success — Consent configured — channel {CHANNEL_ID} is now {CONSENT_TYPE} with a {LANGUAGE} keyword record. Activation-ready.`
+- `Info: Consent already configured — {CONSENT_TYPE}, {N} language record(s). No changes.` (no-op path)
+- `Warning: This channel is PlatformType={x}, not Enhanced — consent fields don't apply here.` (not-enhanced)
+- `Warning: Missing required consent input for {CONSENT_TYPE}: {what}. Re-run and provide it.` (missing-consent-input)
+- `Error: {kind}: {message}` (other failures)
+
+---
+
+## Worked examples
+
+For reference runs of the ImplicitOptIn (opt-out only), ExplicitOptIn, and DoubleOptIn paths, see `references/worked-examples.md`.
+
+---
+
+## Gotchas
+
+Known gotchas — the exact per-ConsentType activation-readiness contract (and its source), comma-separated keyword storage, the "ImplicitOptIn still needs a keyword record" trap, one-record-per-language uniqueness, the Unified-SMS help/French-custom rules, and the OptInPrompt Unified-SMS/WhatsApp/RCS exemption.
+
+**When troubleshooting an unexpected result, or before modifying this skill, load `references/gotchas.md` and follow it.**

package/skills/service-de-channel-consent-configure/references/gotchas.md

@@ -0,0 +1,41 @@
+---
+name: service-de-channel-consent-configure-gotchas
+description: "Load when debugging an unexpected result from service-de-channel-consent-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, and why MsgChannelLanguageKeyword must be written over the Data/SObjects API rather than the Tooling API despite its setupEntity perApiAccess block. 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-consent-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.

package/skills/service-de-channel-consent-configure/references/language-keywords.md

@@ -0,0 +1,84 @@
+# Per-language keyword records: `MsgChannelLanguageKeyword`
+
+Load this when Stage 4 needs to create or update the per-language keyword record for a channel.
+
+## Entity shape
+
+`MsgChannelLanguageKeyword` (key prefix `3Or`, introduced in API 224) is a **master-detail child of `MessagingChannel`**. One record holds all the consent keywords and confirmation messages for **one language** on one channel. A channel can have many of these — one per supported language.
+
+Fields (all string/CLOB except the FK):
+
+| Field | Meaning | Keyword or response |
+| --- | --- | --- |
+| `MasterLanguage` | **Required.** Language locale for this record, e.g. `en_US`, `fr_CA`, `es`, `pt_BR`. | — |
+| `MessagingChannelId` | **Required.** Master-detail FK to the channel (`0Mj…`). Set on create only. | — |
+| `OptInKeywords` | Keywords an end user sends to opt in (e.g. `START,YES,SUBSCRIBE`). | keyword list |
+| `OptInConfirmation` | Reply sent after a successful opt-in. | response |
+| `DoubleOptInKeywords` | Keywords an end user sends to confirm a double opt-in (e.g. `CONFIRM`). | keyword list |
+| `OptOutKeywords` | Keywords an end user sends to opt out (e.g. `STOP,UNSUBSCRIBE,CANCEL`). | keyword list |
+| `OptOutConfirmation` | Reply sent after a successful opt-out. | response |
+| `HelpKeywords` | Keywords an end user sends to get help (e.g. `HELP,INFO`). | keyword list |
+| `HelpResponse` | Reply sent for a help request. | response |
+| `CustomKeywords` | Extra keywords the channel handles. | keyword list |
+| `CustomResponse` | Reply sent for a custom keyword match. | response |
+| `MessagingChannelUsage` | Optional FK (minApiVersion 252); leave unset unless the caller has a specific usage row. | — |
+
+## Keyword storage format — comma-separated strings
+
+Keyword fields hold a **comma-separated string**, not a multi-value/picklist. The UI joins the entered words with `wordArray.toString()` and the server splits them with `TextUtil.splitSimpleAndTrim(value, ",", 0)`. So:
+
+- Store `OptOutKeywords` as the literal string `STOP,UNSUBSCRIBE,CANCEL`.
+- Whitespace around each token is trimmed server-side, but keep it clean: no leading/trailing commas, no empty tokens.
+- Matching is on the whole inbound message against the token list; keep keywords single-word and uppercase by convention (the UI upper-cases nothing automatically — follow the org's existing records if any).
+
+## Create vs update — reuse the record for a language
+
+**There is one record per (channel, language).** Before creating, check the Stage 1 read (`/tmp/cc-keywords.json`) for an existing `MsgChannelLanguageKeyword` whose `MasterLanguage` equals `{LANGUAGE}`:
+
+- **Exists →** `updateRecord` path: PATCH that record's Id with the new field values. Do NOT create a second record for the same language — duplicates confuse the readiness check and the UI.
+- **Doesn't exist →** `createRecord` path: insert a new record, setting `MessagingChannelId={CHANNEL_ID}` and `MasterLanguage={LANGUAGE}` plus the collected keyword/response fields.
+
+### Create
+
+```bash
+sf data create record --target-org '{ORG_ALIAS}' --sobject MsgChannelLanguageKeyword \
+  --values "MessagingChannelId={CHANNEL_ID} MasterLanguage={LANGUAGE} \
+OptOutKeywords='STOP,UNSUBSCRIBE' OptOutConfirmation='You have been unsubscribed.'" \
+  --json > /tmp/cc-kw-write.json
+```
+
+Add `OptInKeywords`/`OptInConfirmation` for ExplicitOptIn, and `DoubleOptInKeywords` for DoubleOptIn.
+
+**Quoting (load-bearing):** `sf data ... --values` splits on spaces, so wrap any value containing a space in single quotes *inside* the double-quoted `--values` string — including keyword CSVs if you ever add spaces after commas, and every confirmation/response message. A comma-separated keyword list with no spaces (`OptOutKeywords=stop,unsubscribe,cancel`) does not need quoting, but a message (`OptOutConfirmation='You have been unsubscribed.'`) always does. An unquoted multi-word value fails with `Malformed key=value pair` (verified live on sdb6c 2026-08-13).
+
+### Update
+
+```bash
+sf data update record --target-org '{ORG_ALIAS}' --sobject MsgChannelLanguageKeyword \
+  --record-id '{KEYWORD_RECORD_ID}' \
+  --values "OptInKeywords='START,YES' OptInConfirmation='You are now subscribed.'" \
+  --json > /tmp/cc-kw-write.json
+```
+
+Check `status` in the JSON result; on non-zero return `{ok:false, kind:"keyword-record-failed", message: ...}`.
+
+## Per-ConsentType minimum (what the readiness check requires)
+
+The record must satisfy, for at least one language, the row matching the channel's `ConsentType` (this is the exact server-side contract from `MessagingChannelReadinessChecker` — see `gotchas.md`):
+
+| ConsentType | Required on the keyword record |
+| --- | --- |
+| ImplicitOptIn | `OptOutKeywords` **and** `OptOutConfirmation` non-null |
+| ExplicitOptIn | above **and** `OptInKeywords` non-null |
+| DoubleOptIn | above **and** `DoubleOptInKeywords` non-null |
+
+`OptInConfirmation` is not part of the base readiness check, but collect it — a channel that opts users in with no confirmation reply is a poor experience.
+
+## Unified SMS extras (only when the channel is Unified SMS)
+
+If the channel is Unified SMS (an Enhanced channel with `MessageType='Text'`; there is no `IsUnifiedMessagingEnabled` column on the Data-API `MessagingChannel` sObject — use `MessageType`), two extra rules apply to the keyword record — the readiness check enforces them:
+
+- **Help is mandatory:** `HelpKeywords` **and** `HelpResponse` must both be non-null.
+- **French locale custom rule:** for a `fr_CA` record, `CustomKeywords` **and** `CustomResponse` must both be non-null.
+
+These are *not* required for non-Unified-SMS channels (WhatsApp, Facebook, etc.), where help/custom are optional. Only enforce them when you've confirmed Unified SMS in Stage 1.