@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-de-channel-create/references/facebook.md

@@ -0,0 +1,154 @@
+# Facebook Messenger — OAuth, page selection, request body, gotchas
+
+`MESSAGE_TYPE=Facebook`. Platform key is the **Facebook Page ID** (numeric, ~15 digits). Unlike the
+other types, Facebook resolves its platform key via a browser-based OAuth flow when `{PAGE_ID}` isn't
+supplied.
+
+## Inputs
+
+- `{PAGE_ID}` — **optional.** If absent, run OAuth → fetch pages → prompt for selection.
+- `{CHANNEL_NAME}` — **optional.** If absent, prompt after page selection.
+
+Most callers will NOT provide `PAGE_ID` upfront.
+
+## Stage 1 preflight caveat
+
+Only run the Stage 1 preflight if `{PAGE_ID}` was provided. If not, skip it — the page id isn't known
+until OAuth + page selection completes. Run the preflight (two-query FK form) after the page is chosen,
+before the insert.
+
+## Stage 2-3: browser-based OAuth + page selection
+
+Facebook requires OAuth authorization to access the customer's pages. This is an interactive,
+browser-based flow — but it **is** headless-driveable end to end: the skill hands the admin the
+exact authorize URL and fetches the page list over Connect REST. It is **not** UI-bootstrap-only.
+
+**Step 1 — get `{AUTH_PROVIDER_ID}` AND the kickoff URL in one query.** The `OauthKickoffUrl` field
+on the AuthProvider is the load-bearing piece — it is the feature-specific Facebook OAuth entry
+point:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, OauthKickoffUrl FROM AuthProvider WHERE DeveloperName = 'LiveMessageSetup' AND ProviderType = 'Facebook' ORDER BY CreatedDate DESC LIMIT 1" \
+  --json > "${SCRATCH_DIR}/fb-authprovider.json"
+```
+Record `{AUTH_PROVIDER_ID}` = `records[0].Id` and `{OAUTH_KICKOFF_URL}` = `records[0].OauthKickoffUrl`
+(e.g. `https://<myDomain>/services/auth/oauth/LiveMessageSetup`). If no record →
+`{ok:false, kind:"missing-authprovider", hint:"LiveMessageSetup AuthProvider not found — org may not have Facebook Messenger enabled"}`.
+
+> **Use `OauthKickoffUrl`, NOT the generic `/services/auth/sso/<orgId>/LiveMessageSetup` SSO URL.**
+> That SSO door runs the AuthProvider's Apex *registration handler* to log a user in; `LiveMessageSetup`
+> has no registration handler (`RegistrationHandlerId=000000000000000`), so the SSO URL dead-ends at
+> `NO_REGISTRATION_HANDLER` — "authentication error." The `/services/auth/oauth/...` kickoff URL is the
+> service-token flow and is the only one that works here. (Verified live on sdb6, 2026-08-26.)
+
+**Step 2 — best-effort token probe / page fetch (same endpoint).** A GET returns the page list when
+the token is valid:
+```bash
+sf api request rest \
+  "/services/data/v{API_VERSION}/connect/livemessage/channels?messageType=Facebook&authProviderId={AUTH_PROVIDER_ID}" \
+  --target-org '{ORG_ALIAS}' > "${SCRATCH_DIR}/fb-pages.json"
+```
+- Body has a `channels[]` array → token *appears* valid; you already have the page list.
+- Body has `errorCode:"AUTH_PROVIDER_NEEDS_AUTH"` → token missing/expired; go to Step 3.
+
+> **The GET is NOT authoritative (gotcha #5).** It serves a *cached* page-list snapshot that can
+> survive the underlying Facebook token expiring — a green GET does not guarantee the Stage 4 POST
+> will succeed. Only the POST validates the token at submit time. If Stage 4 returns
+> `AUTH_PROVIDER_NEEDS_AUTH` despite a passing GET, re-run Step 3 (don't blame the SF session).
+
+**Step 3 — open the authorize URL in a browser.** Append the window-close callback so the flow ends
+on a clean blank page rather than a confusing redirect:
+```bash
+OAUTH_URL="${OAUTH_KICKOFF_URL}?startURL=%2Fpage%2Fwindowclose.jsp"
+case "$(uname -s)" in
+  Darwin) open "${OAUTH_URL}" ;;
+  Linux)  xdg-open "${OAUTH_URL}" ;;
+  MINGW*|MSYS*|CYGWIN*) start "" "${OAUTH_URL}" ;;
+  *) echo "Open this URL to authorize Facebook: ${OAUTH_URL}" ;;
+esac
+```
+Open it automatically; only fall back to printing the URL if no opener exists. Tell the admin: log
+in to the Facebook account that administers the target Page(s), grant access, and **a blank white
+page means success** — close that tab. Then wait for their confirmation (or poll the Step-2 GET
+until `channels[]` appears; ~60 × 3s).
+
+**Step 4 — fetch the page list** (re-run the Step-2 GET now that the token is fresh). Each entry has
+`developerName`, `masterLabel`, `messageType`, `messagingPlatformKey`; entries whose page is already
+wired to a channel **also** carry `id` and `isActive`.
+
+Failure kinds from this stage: `oauth-not-complete` (authorization missing/expired),
+`oauth-failed` (authorization failed or cancelled), `missing-authprovider` (no LiveMessageSetup FB
+AuthProvider on the org).
+
+**Page selection (if `{PAGE_ID}` not supplied):** render **every** page — sorted alphabetically by
+`masterLabel`, annotated with already-connected status, **never truncated** (real orgs have 56+
+pages). Use the write-to-file-plus-render-inline strategy to defeat Bash stdout collapse. Read the
+reply, trim, record `{PAGE_ID}`.
+
+**Channel name (if not supplied):** prompt `Enter a display name for this channel (e.g., "Customer
+Support")`. Empty after trim → re-prompt once; second empty →
+`{ok:false, kind:"missing-input", hint:"CHANNEL_NAME is required"}`.
+
+Failure kinds from this stage: `oauth-not-complete` (authorization missing/expired),
+`oauth-failed` (authorization failed or cancelled).
+
+## Stage 4.2: request body
+
+```bash
+jq -n --arg pageId "${PAGE_ID}" --arg channelName "${CHANNEL_NAME}" \
+  '{messageType:"Facebook", platformType:"Enhanced",
+    messagingPlatformKey:$pageId, messagingChannelName:$channelName, authDetails:{}}' \
+  > "${SCRATCH_DIR}/body.json"
+```
+
+(`${SCRATCH_DIR}` is the per-run scratch dir established in SKILL.md Stage 0.2 — under
+`${outputDir}`/`${TMPDIR}`, never a bare `/tmp` path.)
+
+`authDetails: {}` — empty; the OAuth token lives in the AuthProvider, not the body. `authProviderId`
+is a URL query parameter, never a body field.
+
+**Response classification — classify by `errorCode` first, status second.** The Connect endpoint is
+inconsistent about which HTTP status it pairs with `AUTH_PROVIDER_NEEDS_AUTH` (observed at 401, docs
+imply 400). Always inspect `response[0].errorCode` (or `.errorCode` if the body is an object) before
+status-based classification:
+
+| `errorCode` (any status) | Handling |
+| --- | --- |
+| `AUTH_PROVIDER_NEEDS_AUTH` | `{ok:false, kind:"oauth-not-complete", hint:"Facebook OAuth authorization is missing or expired — re-run Stage 2 to refresh the FB token"}`. |
+| `DUPLICATE_VALUE` | Re-run Stage 1 preflight; emit success `created:false, path:"connect-duplicate"`. |
+
+Then the two 401 flavors (disambiguate by errorCode, NOT status):
+- `AUTH_PROVIDER_NEEDS_AUTH` → `oauth-not-complete` (re-run OAuth; SF session is fine).
+- empty body / `INVALID_SESSION_ID` → `{ok:false, kind:"auth", hint:"SF session token invalid — run 'sf org login web'"}`.
+
+Telling the user to run `sf org login web` when the FB token is the problem sends them down a dead
+end — the errorCode is what distinguishes the two.
+
+## Gotchas
+
+1. **The 401 is usually NOT an SF token problem.** `AUTH_PROVIDER_NEEDS_AUTH` at 401 means the
+   AuthProvider's stored Facebook token is stale — re-run OAuth, not `sf org login web`. Classify by
+   errorCode first.
+2. **Never truncate the page list.** 56+ pages is normal; write-to-file-plus-render-inline defeats
+   Bash stdout collapse.
+3. **MCU lands as `DeploymentStatus=New` for Facebook** (WhatsApp lands as `Disabled`). Both are
+   valid `→ Provisioning` sources — don't assert a specific starting status in Stage 5. (Verified:
+   fresh FB insert → `MessagingChannelUsage.DeploymentStatus=New`, `DeploymentType=Conversation`.)
+4. **POST-response projection is not authoritative** for `masterLabel` / `developerName` — trust the
+   Stage 5 verify SOQL. Verified: POST returned `developerName:"Facebook_988507654355940"` /
+   `masterLabel:"988507654355940"`, but SOQL showed `FACEBOOK_US_988507654355940` (uppercase +
+   country-code suffix) / the real `messagingChannelName` as `MasterLabel`.
+5. **The page-list GET is a cached snapshot, not a live token check.** `GET
+   /connect/livemessage/channels?messageType=Facebook&authProviderId=...` can return 200 with the
+   full page list even after the underlying Facebook token has expired; only the Stage 4 POST
+   validates the token at submit time. Use the GET for the page list, never as proof the POST will
+   succeed. If the POST returns `AUTH_PROVIDER_NEEDS_AUTH`, re-open `OauthKickoffUrl` (Stage 2-3),
+   don't run `sf org login web`.
+6. **Consent is auto-seeded on insert — do NOT assume the channel lands consent-blank.** A fresh
+   Connect insert comes back with `ConsentType=ImplicitOptIn` already set and a default `en_US`
+   `MsgChannelLanguageKeyword` already created (opt-out keywords `cancel,stopall,stop,unsubscribe,
+   end,quit` + a canned confirmation, plus a `help` keyword). The downstream consent step is
+   therefore often a **no-op** on a fresh channel (or an *upgrade* if the caller wants
+   Explicit/DoubleOptIn), not a guaranteed write. (Verified live on sdb6, 2026-08-26, channel
+   `0MjSG000000TXdJ0AW`.)

package/skills/service-de-channel-create/references/line.md

@@ -0,0 +1,66 @@
+# LINE — token verify, request body, gotchas
+
+`MESSAGE_TYPE=Line`. Platform key is the **LINE channel id** (numeric, from the LINE Developers
+Console — not the LINE user id). Channel secret + access token go in `authDetails`.
+
+## Inputs
+
+- `{LINE_CHANNEL_ID}` — LINE channel id. Numeric string. Sent as `messagingPlatformKey`.
+- `{LINE_CHANNEL_SECRET}` — LINE channel secret (webhook verification secret). Sent in
+  `authDetails.client_secret`.
+- `{LINE_ACCESS_TOKEN}` — LINE long-lived channel access token. Sent in `authDetails.access_token`.
+- `{CHANNEL_NAME}` — optional. Defaults to `LINE_{LINE_CHANNEL_ID}` if not provided.
+- `{VERIFY_TOKEN_FIRST}` — optional boolean, default `true`. When `true`, validate the token against
+  LINE's public API before insert.
+
+## Stage 2-3: optional token preflight
+
+If `{VERIFY_TOKEN_FIRST}` is `true`, validate the token before paying the full insert cost. This is
+a **third-party** call to LINE, so it uses `curl` (not `sf api request rest`) — the LINE token is
+not a Salesforce credential:
+
+```bash
+curl -sS -o "${SCRATCH_DIR}/line-token.json" -w '\n%{http_code}' \
+  -H "Authorization: Bearer ${LINE_ACCESS_TOKEN}" \
+  "https://api.line.me/v2/bot/info"
+```
+
+- HTTP 200 → token valid, proceed.
+- HTTP 401 / non-200 → `{ok:false, kind:"line-token-invalid", hint:"LINE access token rejected — regenerate in LINE Developers Console and retry"}`.
+
+If `VERIFY_TOKEN_FIRST=false`, skip — the Connect POST will surface a token error later, with less
+clear signal.
+
+(`${SCRATCH_DIR}` is the per-run scratch dir established in SKILL.md Stage 0.2 — under
+`${outputDir}`/`${TMPDIR}`, never a bare `/tmp` path.)
+
+## Stage 4.2: request body
+
+```json
+{"messageType":"Line","platformType":"Enhanced",
+ "messagingPlatformKey":"{LINE_CHANNEL_ID}",
+ "messagingChannelName":"{CHANNEL_NAME}",
+ "authDetails":{"client_secret":"{LINE_CHANNEL_SECRET}","access_token":"{LINE_ACCESS_TOKEN}"}}
+```
+
+**Write the body to a file** — the access token is long and can contain shell-hostile characters.
+
+Response classification: same as the shared table (see `connect-insert.md`), plus — on `400` whose
+message contains "access token" / "channel secret" / "Line" — emit
+`{ok:false, kind:"line-token-invalid", message, hint:"LINE creds rejected — verify channel secret + access token in LINE Developers Console"}`.
+
+## Gotchas
+
+1. **`messagingPlatformKey` is the LINE channel id**, not the LINE user id — the numeric id shown in
+   the Developers Console for the Messaging API channel.
+2. **`authDetails` keys are exactly `client_secret` + `access_token`.** Don't rename them;
+   `LiveMessageSetupServiceImpl.addChannel` looks for exactly those strings.
+3. **Long-lived vs short-lived tokens.** The Setup wizard assumes long-lived (Developers Console).
+   Short-lived tokens (Channel Access Token v2.1 API) insert fine but expire, silently stopping the
+   channel. Use long-lived for production.
+4. **No third-party registration at activation.** Unlike WhatsApp, LINE has no `/register` call —
+   `service-de-channel-activate` transitions MCU→Active without any external callout, so
+   `Provisioning` is essentially invisible (~1s).
+5. **`sf api request rest` manages the SF OAuth session** — no `ACCESS_TOKEN`/`INSTANCE_URL` shell
+   variables. The LINE token is the only credential handled by `curl`, and only for the Stage 2-3
+   verify.

package/skills/service-de-channel-create/references/sms.md

@@ -0,0 +1,98 @@
+# SMS (Text) — phone-number platform key, accepted-but-ignored smsProvider, gotchas
+
+`MESSAGE_TYPE=Text`. There is **no `"SMS"` enum value** — SMS channels are `Text` everywhere in the
+platform (the `MessageTypeEnum` API value is `"Text"`; the DB value is `0`). Send `"messageType":"Text"`.
+
+Platform key is the **phone number / SMS code itself** — the literal long code, toll-free number, or
+short code string the caller wants to send from (e.g. `18005551234`). It is stored verbatim into
+`MessagingChannel.MessagingPlatformKey` and used as-is for the activation-time ESP lookup, so it must
+match exactly what was provisioned for that code. Don't reformat it; send whatever the caller gives.
+
+**Prerequisite (caller's responsibility, NOT handled by this skill):** the phone number / code must
+already be provisioned to the org through the SMS code-request flow. This skill does **not** allocate a
+number, request a short code, or run any code-provisioning step — it only inserts the channel record for
+a number the caller already has. If the number isn't provisioned yet, the insert may still succeed (the
+record is created inactive) but activation will later fail at the ESP registration step.
+
+## Inputs
+
+- `{SMS_NUMBER}` — the phone number / short code / toll-free number, as a plain string. Sent as
+  `messagingPlatformKey`. **Required.**
+- `{SMS_PROVIDER}` — the code-provider identifier for this number (the "messaging provider" / SMS
+  provider). Sent as `smsProvider`. The `smsProvider` **key must be present in the body**, but the
+  Connect endpoint only checks that the field *exists* — it does not check the **value** against any
+  provider registry, and it does not persist the value anywhere. Sending an **empty string**
+  (`"smsProvider":""`) inserts the channel successfully; **omitting the key entirely** fails with
+  errorCode `ILLEGAL_QUERY_PARAMETER_VALUE`, message `"SMS provider is missing "`. Tested against
+  `sdb6` (API v69.0): an empty-provider channel and a real-provider channel are byte-identical across
+  every queryable `MessagingChannel` field — there is no `ExternalChannelConfigJson` /
+  `codeProviderDetails` field on the object (the only provider/config-adjacent fields are
+  `IsoCountryCode` and `RoutingConfigurationId`), so the value has no storage location and leaves no
+  observable trace. Pass the real provider when the caller knows it, else default to `""` — never omit
+  the key.
+- `{CHANNEL_NAME}` — display name (`messagingChannelName`). Recommended; falls back to the number if
+  omitted, but supplying it keeps the Setup UI label meaningful. Note: the insert **response** echoes
+  `masterLabel` as the bare number, but the **persisted** `MessagingChannel.MasterLabel` holds the
+  supplied `messagingChannelName` (tested against `sdb6`, API v69.0). Read the stored record — not the
+  POST response — if you need the display label back.
+- `{ISO_COUNTRY_CODE}` — optional, default `US`. Participates in the dedupe query and the generated
+  `DeveloperName`, so pass the real country if the number is non-US.
+
+## Stage 2-3: none
+
+SMS has no insert-time third-party prerequisite that this skill performs. The number-provisioning /
+code-request step is upstream and out of scope (see the prerequisite note above). The ESP registration
+(`registerCsotSms` → Admin API ESP-ID lookup keyed by the platform key) runs at **activation**, not
+insert — so an unprovisioned number surfaces as an activation-time `provisioning-error`, not an insert
+failure.
+
+## Stage 4.2: request body
+
+```json
+{"messageType":"Text","platformType":"Enhanced",
+ "messagingPlatformKey":"{SMS_NUMBER}",
+ "messagingChannelName":"{CHANNEL_NAME}",
+ "smsProvider":"{SMS_PROVIDER}",
+ "isoCountryCode":"{ISO_COUNTRY_CODE}"}
+```
+
+**`smsProvider` is the Text-specific field the body must always carry** — no other type sends it, and
+Text cannot be inserted if the key is missing. Its value is not validated or stored (see Inputs), so
+default to `""` when the caller didn't supply a provider — but **always include the key**. **No
+`authDetails` / `externalAccountId` / auth tokens** — Text uses none of those (`authDetails` is read
+only by MsCopilot / GoogleChat / Slack / Line). `authProviderId` in the URL query string is **optional
+for Text** (the v258 Connect signature added a Text-only path that doesn't require it) — this is the
+whole reason Stage 4.1 treats a missing `LiveMessageSetup` AuthProvider as terminal for every other type
+but non-fatal for `Text`. Send `authProviderId` only when Stage 4.1 actually resolved one (harmless for
+Text); when it didn't, `Text` proceeds and the POST omits the parameter entirely. **Do not append an
+empty `?authProviderId=`** — a blank value is rejected with `ILLEGAL_QUERY_PARAMETER_VALUE`, so a Text
+insert on an org with no LiveMessage setup must hit the bare endpoint.
+
+Response classification: same as the shared table (see `connect-insert.md`), plus — on an error whose
+message mentions "SMS provider" / "provider is missing" (observed errorCode
+`ILLEGAL_QUERY_PARAMETER_VALUE`) — the body dropped the `smsProvider` key entirely; re-send with the
+key present (an empty string `""` is fine). This shouldn't happen if the body is built from the shape
+above, which always includes the key.
+
+## Gotchas
+
+1. **The enum is `Text`, not `SMS`.** `"messageType":"SMS"` is rejected — the picklist / SOQL / Connect
+   enum value is `Text`. The user-facing concept "SMS" maps to `Text` in every API surface.
+2. **`smsProvider` key is mandatory; its value is not.** The Connect endpoint checks only that the
+   field is present — omitting it fails with errorCode `ILLEGAL_QUERY_PARAMETER_VALUE`, message
+   `"SMS provider is missing "`, but an empty string (`"smsProvider":""`) inserts fine, and the
+   endpoint neither checks the value against a provider registry nor stores it anywhere (no
+   `ExternalChannelConfigJson`/`codeProviderDetails` field exists on `MessagingChannel`; tested
+   against `sdb6`, API v69.0). Always send the key; default the value to `""` when unknown. It is a
+   code-provider label, not an auth secret.
+3. **`MessagingPlatformKey` is the number/code string itself**, stored verbatim. There's no separate
+   phone-number ID (contrast WhatsApp, where the platform key is a Phone Number ID distinct from the
+   WABA ID). Send the exact provisioned code string; this skill doesn't normalize to E.164.
+4. **This skill doesn't provision the number.** It inserts a channel record for a number the caller
+   already has. Number allocation / short-code requests are a separate upstream flow, intentionally out
+   of scope here — the caller must already know their number and its provider.
+5. **Activation, not insert, is where an unprovisioned number bites.** `registerCsotSms` does the Admin
+   API ESP-ID lookup keyed by the platform key at activation time. Insert only creates the inactive
+   record + its MCU.
+6. **Fresh MCUs start in `DeploymentStatus=New`** (`Disabled` is the post-deactivation state) — same as
+   every other type. Don't assert a specific starting status in Stage 5.

package/skills/service-de-channel-create/references/whatsapp.md

@@ -0,0 +1,98 @@
+# WhatsApp — prerequisites, request body, gotchas
+
+`MESSAGE_TYPE=WhatsApp`. Platform key is the **Phone Number ID** (not the WABA ID, not the display
+number). WABA ID is sent separately as `externalAccountId`.
+
+## Inputs
+
+- `{WABA_ID}` — WhatsApp Business Account ID. Numeric string, ~15 digits. Sent as
+  `externalAccountId`. **NOT the same as Phone Number ID** — a WABA can contain multiple phone
+  numbers. Meta Business Manager → WhatsApp Accounts → (your account) → Account ID at top.
+- `{PHONE_NUMBER_ID}` — Meta phone number ID. Numeric string, ~15 digits. Sent as
+  `messagingPlatformKey`. (NOT the display phone number like `+1 650-555-0199`.) **Must differ from
+  WABA_ID.** Meta Business Manager → WhatsApp Accounts → (your WABA) → Phone Numbers tab → Phone
+  number ID column.
+- `{CHANNEL_NAME}` — display name (`messagingChannelName`), shown as "Channel Name" in Setup →
+  Messaging Settings. Required — prompt if not supplied. Never auto-default to the phone number id:
+  the id is opaque and produces a confusing UI (both columns show the same digits).
+- `{ISO_COUNTRY_CODE}` — optional, two-letter ISO-3166 alpha-2 (e.g. `US`). Default `US`. Passed as
+  `isoCountryCode`.
+
+## Stage 2-3: WABA partnership + SF-side management (prereq)
+
+Runs only when Stage 1 preflight found no existing channel. Execution order on a fresh run:
+Stage 1 → Stage 2 (linking) → Stage 3 (manage-WABA) → Stage 4 (insert). On a preflight-hit resume,
+these never run — the partnership and the SF-side webhook/credit-line share are both in place by
+definition (the prior insert couldn't have succeeded otherwise).
+
+**Stage 2 — customer-side partnership.** Confirm the WABA is shared with Salesforce in Meta Business
+Suite. There's no Graph API to probe this without a customer Meta token, so invoke
+`service-de-waba-integrate` and handle its envelope:
+- success → proceed to Stage 3
+- `{ok:false, kind:"partnership-blocked"}` → propagate; resolve on Meta side and retry
+- `{ok:false, kind:"user-declined"}` → propagate; re-run when ready
+
+**Stage 3 — SF-side management.** The customer-side share from Stage 2 alone does not subscribe SF's
+webhook or share SF's Meta line of credit. Call the sanctioned Connect endpoint. **The WABA id (and
+phone id) go in the URL query string, NOT the JSON body** — the endpoint reads `wabaId`/`phoneId`
+from the query and ignores a body `externalAccountId`. Send an empty body:
+
+```bash
+sf api request rest \
+  "/services/data/v{API_VERSION}/connect/livemessage/whatsapp/business-account?authProviderId=${AUTH_PROVIDER_ID}&wabaId=${WABA_ID}&phoneId=${PHONE_NUMBER_ID}" \
+  --method POST --target-org '{ORG_ALIAS}' \
+  --header 'Content-Type: application/json' --header 'Accept: application/json' \
+  --include
+```
+On failure emit
+`{ok:false, kind:"waba-manage-failed", hint:"manageWhatsAppBusinessAccount failed — SF could not subscribe its webhook / share credit line with this WABA. Most likely: WABA not actually shared yet (partnership landed Meta-side but hasn't propagated), or the WABA id is wrong.", message:"..."}`.
+
+> **Do NOT put the WABA id in the body** (gotcha #6). A body of `{"externalAccountId":"<WABA_ID>"}` —
+> or even `{"wabaId":"<WABA_ID>"}` — returns `400 INVALID_API_INPUT "wabaId is required"`, because the
+> endpoint only reads `wabaId`/`phoneId` from the query string. Pass both as query params with an empty
+> body. (Verified live: documented body shape → `"wabaId is required"` on sdb6; query-param shape → 201
+> on projectCodeyDemo, 2026-08-26.)
+
+Together Stage 2 + Stage 3 produce a WABA fully ready for the Stage 4 channel insert.
+
+## Stage 4.2: request body
+
+```json
+{"messageType":"WhatsApp","platformType":"Enhanced",
+ "messagingPlatformKey":"{PHONE_NUMBER_ID}",
+ "messagingChannelName":"{CHANNEL_NAME}",
+ "externalAccountId":"{WABA_ID}",
+ "isoCountryCode":"{ISO_COUNTRY_CODE}"}
+```
+
+The MCU lands in a pre-activation `DeploymentStatus` (observed as both `Disabled` and `New` on fresh
+WhatsApp inserts across orgs; Facebook lands as `New`). Any pre-activation value is a valid
+`→ Provisioning` source state — don't assert a specific one; just confirm the MCU exists.
+
+## Type-specific failure kinds
+
+- `partnership-blocked` — from Stage 2 (`service-de-waba-integrate`).
+- `user-declined` — user cancelled the WABA-linking prompt.
+- `waba-manage-failed` — from Stage 3 (SF-side `manageWhatsAppBusinessAccount`).
+- `meta-precondition` — Connect rejected the insert (WABA not shared, phone not OTP'd on Meta side,
+  etc.); hint `"Connect API rejected the request — WABA not shared, phone not OTP'd on Meta side"`.
+
+## Gotchas
+
+1. **WABA_ID ≠ PHONE_NUMBER_ID.** A WABA can contain multiple phone numbers. Same value for both →
+   cryptic activation failures ("WhatsApp number registration failed"). Stage 0.1 asserts they differ.
+2. **PATCH activation is synchronous with Meta `/register`** — WhatsApp channels take 15-30s to
+   activate (vs ~1s for Apple/LINE, which have no external callout). Not this skill's concern, but
+   explains the downstream latency difference in `service-de-channel-activate`.
+3. **`developerName` follows the server-side format** (e.g. `WHATSAPP_US_<phoneNumberId>`), NOT the
+   Connect response's pre-DB projection. Trust the DB (Stage 5 verify), not the 201 body.
+4. **Fresh-insert MCU `DeploymentStatus` varies** — observed as both `Disabled` and `New` on WhatsApp
+   across orgs (`New` for Facebook). Don't assert a specific starting status in Stage 5 — just that the
+   MCU exists; any pre-activation value is a valid `→ Provisioning` source.
+5. **Field/relationship-name variance across orgs.** Use the two-query FK form (never the
+   `MessagingChannelUsages` child subquery), and the trimmed universal field set — `ExternalAccountId`
+   and `MessagingPlatform` are absent on some orgs (`INVALID_FIELD` on `wadtesting`).
+6. **WABA-management call takes `wabaId`/`phoneId` in the URL query, not the body.** The documented
+   body shape `{"externalAccountId":"<WABA_ID>"}` returns `400 INVALID_API_INPUT "wabaId is required"`
+   (as does `{"wabaId":...}` in the body). Pass `?...&wabaId=<WABA_ID>&phoneId=<PHONE_NUMBER_ID>` with an
+   empty body — see Stage 3.

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

@@ -0,0 +1,70 @@
+---
+name: service-de-channel-create-worked-examples
+description: "Load for end-to-end traces of a channel insert per type — a fresh Connect-path insert (Apple, verified on wadtesting), a preflight short-circuit re-run, and the Facebook interactive OAuth → page-selection path. Illustrative only; the authoritative flow is the parent SKILL.md stages."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-create
+---
+
+# Worked examples (per type)
+
+## Apple Business Chat — fresh insert (real trace, wadtesting 2026-04-30)
+
+`messagingcore-wadtesting2.test1.my.pc-rnd.salesforce.com`. Inputs:
+`APPLE_BC_ID=c02e9350-f526-42dc-9e8d-cec2edf59487`, `CHANNEL_NAME=Apple Channel`.
+
+- **Stage 1** — preflight SOQL (two-query FK form) returns 0 rows. Proceed.
+- **Stage 4.1** — `SELECT Id FROM AuthProvider WHERE DeveloperName='LiveMessageSetup'` → one row,
+  captured as `{AUTH_PROVIDER_ID}` (org-specific).
+- **Stage 4.2** — body `{"messageType":"AppleBusinessChat","platformType":"Enhanced","messagingPlatformKey":"c02e9350-...","messagingChannelName":"Apple Channel"}`;
+  POST to `.../connect/livemessage/channels?authProviderId=${AUTH_PROVIDER_ID}`. Response 201:
+  ```json
+  {"id":"0MjSG000000MNUD0A4","developerName":"AppleBusinessChat_c02e9350_...",
+   "isActive":false,"masterLabel":"c02e9350-...","messageType":"AppleBusinessChat",
+   "messagingPlatformKey":"c02e9350-..."}
+  ```
+  The `masterLabel`/`developerName` in the body are **stale input-rep projections** — the DB row uses
+  `MasterLabel="Apple Channel"` and the canonical `APPLEBUSINESSCHAT_US_c02e9350_...`.
+- **Stage 5** — verify SOQL confirms `MasterLabel="Apple Channel"`,
+  `DeveloperName="APPLEBUSINESSCHAT_US_c02e9350_..."`, `IsActive=false`; MCU `0gLSG0000003Kjl2AE`,
+  `DeploymentType=Conversation`, `DeploymentStatus=New`.
+- **Stage 6** — success envelope, `path:"connect"`, `created:true`.
+
+Downstream chain ran immediately after: routing PATCH → 204; activation PATCH
+(`DeploymentStatus="Provisioning"`) → 204 in ~1s (Apple hits the observer's `default` branch — no
+external callout).
+
+**Gotcha surfaced:** the first POST omitted `?authProviderId=` (based on an older skill version
+claiming "Apple doesn't use authProviderId") → `400 ILLEGAL_QUERY_PARAMETER_VALUE`. Corrected:
+`authProviderId` is universally required.
+
+## LINE — fresh insert (illustrative)
+
+Inputs: `LINE_CHANNEL_ID=2001234567`, secret + long-lived token, `CHANNEL_NAME=Support LINE Channel`.
+
+- **Stage 1** preflight → 0 rows.
+- **Stage 2-3** (optional token verify) → `GET https://api.line.me/v2/bot/info` returns 200. Valid.
+- **Stage 4.2** body includes `authDetails:{client_secret, access_token}`. Response 201 →
+  `{id:"0MjSG000000Fd2m0AD", developerName:"LINE_2001234567", ...}`.
+- **Stage 5** verify → channel + one MCU `DeploymentType=Conversation`. Success `path:"connect"`.
+
+## Preflight short-circuit (any type)
+
+Re-running an insert for a channel that already exists:
+- **Stage 1** preflight SOQL finds `records.length === 1`. Records `{CHANNEL_ID}`, `{DEVELOPER_NAME}`,
+  `{IS_ACTIVE}`; second query picks up `{MCU_ID}`.
+- Emits success envelope with `path:"preflight", created:false`. Stages 2-5 never run. This is the
+  idempotency guard (`MessagingChannel` rows aren't deletable via standard means).
+
+## Facebook — interactive OAuth → page selection (illustrative)
+
+`PAGE_ID` not supplied.
+- **Stage 1** skipped (no page id yet).
+- **Stage 2-3** — look up `{AUTH_PROVIDER_ID}`; the stored FB token is stale, so open the OAuth URL
+  in a browser, wait for the user to authorize, then fetch the page list. Render all pages sorted by
+  `masterLabel`, annotated with connected status, untruncated. User selects one → `{PAGE_ID}`. Prompt
+  for `{CHANNEL_NAME}`. Now run the Stage 1 preflight for the chosen page id.
+- **Stage 4.2** body `{..., messagingPlatformKey:"{PAGE_ID}", authDetails:{}}`. If the response
+  errorCode is `AUTH_PROVIDER_NEEDS_AUTH` (may arrive as 400 OR 401), emit `oauth-not-complete` and
+  re-run OAuth — do NOT tell the user to run `sf org login web` (the SF session is fine).
+- **Stage 5** verify → MCU `DeploymentStatus=New` (Facebook lands as `New`, not `Disabled`). Success.