Service De Channel Consent 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

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:

{"ok": true, "noop": true, "consentType": "ImplicitOptIn|ExplicitOptIn|DoubleOptIn", "languageKeywordIds": ["3Or..."], "message": "Consent already configured and activation-ready"}

Success — consent configured:

{"ok": true, "consentType": "ExplicitOptIn", "channelFieldsSet": ["ConsentType","OptInPrompt"],
 "languageKeywordId": "3Or...", "language": "en_US", "created": true|false, "activationReady": true}

Precondition / validation not met:

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

{"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.

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

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

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

Opt-in prompt (sent when a reply doesn't match an opt-in keyword):

For DoubleOptIn, also:

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.

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