forcedotcom/sf-skills / skills/service-de-headless-channel-configure
service-de-headless-channel-configure
VerifiedTop-level orchestrator: given a messaging channel type and its inputs, produces an activated Enhanced `MessagingChannel` in the target org — without the Meta/LINE/Apple setup popups. Prompts for `{MESSAGE_TYPE}` if not supplied, then sequences insert → route → consent → activate → requested settings (auto-responses, keywords, session inactivity) via the type-agnostic dispatcher (`service-de-channel-create`) plus the shared routing/settings/activation leaves, and reports every requested setting as configured, not applicable, or failed. Resumes from partial state on re-run. Use to set up an Enhanced channel (WhatsApp, Facebook, LINE, Apple, SMS) end-to-end, bypassing in-org setup popups. Do not use for a single stage of an already-inserted channel — use the matching leaf skill (`service-de-channel-activate`, `service-de-channel-settings-configure`, `service-de-channel-routing-configure`) instead.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.7 KB |
| references/gotchas.md | markdown | 4.7 KB |
| references/inputs.md | markdown | 4.8 KB |
| references/output-envelopes.md | markdown | 4.6 KB |
| references/partial-success.md | markdown | 1.3 KB |
| references/requested-settings.md | markdown | 2.9 KB |
| references/terms-and-conditions.md | markdown | 3.5 KB |
| references/worked-examples.md | markdown | 9.6 KB |
references/worked-examples.md
View on GitHub# Worked examples: `service-de-headless-channel-configure`
Six reference traces: a fresh WhatsApp run (the most common path), a resume after a mid-flow failure, an Apple Business Chat dispatch (to show type-agnostic flow), an unsupported-type rejection, a Facebook run with requested settings, and a settings-only run on an already-active channel. Read these when you need to see the exact envelope shapes the orchestrator emits at each outcome.
---
## Worked example: fresh WhatsApp channel on test1
Input (hypothetical, against `test1`):
- `MESSAGE_TYPE=WhatsApp`
- `WABA_ID=1558753535400324`
- `PHONE_NUMBER_ID=1005595132638768`
- `CHANNEL_NAME` = (omitted)
**Stage 0**: type known from input. `{PLATFORM_KEY} = PHONE_NUMBER_ID`. Required WhatsApp inputs (`WABA_ID`, `PHONE_NUMBER_ID`) both present — proceed.
**Stage 1**: preflight SOQL keyed off `MessagingPlatformKey=1005595132638768 AND MessageType='WhatsApp'` returns 0 records → `CURRENT_STATE=fresh`. First step: insert.
**Stage 2** (insert): `service-de-channel-create` runs (with `MESSAGE_TYPE=WhatsApp`):
- Its Stage 1 preflight (same SOQL; still empty)
- Its Stage 2 linking prereq (`service-de-waba-integrate`) — user confirms Meta partnership is in place
- Its Stage 3 Connect API POST — inserts `MessagingChannel 0MjSG...` + MCU `0gLSG...`
- Its Stage 4 verify — MCU subquery returns one row with `DeploymentType=Conversation`, `DeploymentStatus=Disabled`
Returns `{ok:true, channelId:"0MjSG...", mcuId:"0gLSG...", developerName:"WHATSAPP_US_...", isActive:false, messageType:"WhatsApp", path:"connect", created:true, durationMs:3210}` to the orchestrator. `STEPS_RUN=["insert"]`.
**Stage 3** (route): `service-de-channel-routing-configure` prompts user. User picks existing `Messaging_Queue` (`00GSG0000000LSf2AM`). PATCH lands. `STEPS_RUN=["insert","route"]`.
**Stage 3.5** (consent): `service-de-channel-settings-configure` runs. The insert auto-seeded `ConsentType=ImplicitOptIn` + a default opt-out `MsgChannelLanguageKeyword` (STOP-family + confirmation), so the leaf's Stage 1 finds the channel already activation-ready and returns `noop:true` — no write needed. (Had the user asked for ExplicitOptIn/DoubleOptIn or custom keywords, the leaf would upgrade it here.) `STEPS_RUN=["insert","route"]`, `STEPS_SKIPPED=["consent"]`.
**Stage 4** (activate): `service-de-channel-activate` PATCHes `MessagingChannelUsage.DeploymentStatus='Provisioning'` via REST. The PATCH blocks synchronously until the server-side observer chain finishes, then returns 204 with `DeploymentStatus=Active` → `channel.IsActive=true` in ~15-21s (Meta `/register` round-trip). `STEPS_RUN=["insert","route","activate"]`.
**Stage 5**: Emits:
```json
{"ok":true, "messageType":"WhatsApp", "channelId":"0MjSG...", "mcuId":"0gLSG...",
"channelName":"+1 650-555-0199", "sessionHandlerId":"00GSG0000000LSf2AM",
"queueName":"Messaging Queue", "isActive":true,
"stepsRun":["insert","route","activate"], "stepsSkipped":["consent"], "totalDurationMs":8421}
```
User sees `Success — WhatsApp channel '+1 650-555-0199' is live on test1.` plus the detail lines.
---
## Worked example: resume after routing failure
Same inputs as above, but imagine Stage 3 failed the first time because the user's session lost permission to deploy Queue metadata.
**First run** — orchestrator gets through stages 0-2, stage 3 fails:
```json
{"ok":false, "failedStep":"route", "failedStepIndex":2, "failedStepTotal":4,
"leafEnvelope":{"ok":false,"kind":"metadata-deploy-failed","message":"INSUFFICIENT_ACCESS_OR_READONLY"},
"stateSoFar":{"channelId":"0MjSG...", "mcuId":"0gLSG...",
"sessionHandlerId":null, "isActive":false,
"stepsRun":["insert"], "stepsSkipped":[]},
"resumeHint":"fix the routing issue above, then re-run this skill — step 1 will be skipped automatically"}
```
User fixes the permission, re-runs with the same inputs.
**Second run**:
- **Stage 0** type known (user provided `WhatsApp` again). Inputs validated.
- **Stage 1** preflight now returns 1 record: `{channelId, IsActive:false, SessionHandlerId:null, FallbackQueueId:null, ...}` → `CURRENT_STATE=inserted-no-routing`. First step: route.
- **Stage 2** (insert): skipped. `STEPS_SKIPPED=["insert"]`. The dispatcher + all per-type prereqs (including the WABA linking prompt) are skipped entirely, which is the whole point of preflight short-circuiting.
- **Stage 3** (route): runs fresh, succeeds this time. `STEPS_RUN=["route"]`.
- **Stage 3.5** (consent): the channel was inserted on the *first* run, so its consent was auto-seeded then (`ConsentType=ImplicitOptIn` + default opt-out keyword). The leaf's Stage 1 finds it already activation-ready and returns `noop:true` — no write. `STEPS_SKIPPED=["consent"]`. (Only an explicit Explicit/DoubleOptIn or custom-keyword request would make this a real write.)
- **Stage 4** (activate): runs. `STEPS_RUN=["route","activate"]`.
- **Stage 5**: success, with `stepsRun: ["route","activate"]` and `stepsSkipped: ["insert","consent"]` visible in the report.
The user sees that resume happened, and the total time reflects only what was re-done.
---
## Worked example: Apple Business Chat dispatch
Shows the type-agnostic flow — same orchestrator, different leaf via the dispatcher.
Input:
- `MESSAGE_TYPE=AppleBusinessChat`
- `APPLE_BC_ID=abc123-def456-...` (GUID)
- `CHANNEL_NAME="Acme Apple Support"`
**Stage 0**: type known. `{PLATFORM_KEY} = APPLE_BC_ID`. Apple-required inputs (`APPLE_BC_ID`, `CHANNEL_NAME`) present — proceed.
**Stage 1**: preflight SOQL keyed off `MessagingPlatformKey='abc123-...' AND MessageType='AppleBusinessChat'` returns 0 records → `CURRENT_STATE=fresh`.
**Stage 2** (insert): `service-de-channel-create` runs with `MESSAGE_TYPE=AppleBusinessChat`. The user supplies the Apple BC Account ID (obtained on the Apple Business Register side beforehand), and the skill inserts the channel. Returns with `messageType:"AppleBusinessChat"`.
**Stages 3-5**: routing and activation are identical to the WhatsApp path — they operate on `MessagingChannel.Id` + `MessagingChannelUsage.Id`, which don't care about message type.
Final envelope identical shape to the WhatsApp run but with `messageType: "AppleBusinessChat"`.
---
## Worked example: unsupported type rejection
User invokes without specifying a type, gets the prompt, then types `wechat`.
**Stage 0**: prompt shows `1) WhatsApp / 2) Line / 3) AppleBusinessChat / 4) Facebook / 5) Text (SMS)`. Input `wechat` doesn't match any — orchestrator re-prompts or halts with:
```json
{"ok":false, "kind":"unsupported-type", "messageType":"wechat",
"supportedTypes":["WhatsApp","Line","AppleBusinessChat","Facebook","Text"],
"hint":"WeChat needs its own insertion leaf, not yet built — supported types are WhatsApp, Line, AppleBusinessChat, Facebook, Text"}
```
Alternatively, if the orchestrator forwards `WeChat` directly to the dispatcher without validating upfront, the dispatcher (`service-de-channel-create`) emits the same `unsupported-type` envelope and the orchestrator passes it through with `failedStep: "insert"`.
Either way the user gets a clear "this type isn't supported" message rather than a confusing mid-flow error.
---
## Worked example: Facebook with auto-responses and an idle timeout
Prompt: *"Set up my Facebook Messenger channel for page 103663378691289, route it to Default_Queue. Also add auto-responses: 'Thanks for reaching out!' initially, 'You're now connected with an agent.' when an agent engages, and 'Are you still there?' when the customer goes idle after 10 minutes — and set the session idle timeout to 15 minutes."*
**Stage 0**: `MESSAGE_TYPE=Facebook`, `PAGE_ID=103663378691289`, `QUEUE=Default_Queue`. `{REQUESTED_SETTINGS}` = `auto-response:InitialResponse`, `auto-response:AgentEngagedResponse`, `auto-response:EndUserIdleResponse` (`responseTimeoutInMins=10`), `inactivity:endUserIdleTimeOut` (15).
**Stages 0.5–4**: T&C accepted; preflight `fresh`; AuthProvider present; insert, route (to the named queue, no prompt), consent no-op, activate. `STEPS_RUN=["insert","route","activate"]`, `STEPS_SKIPPED=["consent"]`.
**Stage 4.5**: one `service-de-channel-settings-configure` call with `FACETS=[auto-responses, inactivity]`. The leaf returns `facet-not-applicable` for `endUserIdleTimeOut` (MIAW-only), and attempts the three auto-responses in one metadata deploy. If the deploy hits the known Facebook metadata-update defect, all three land in `failed` with the leaf's `metadata-deploy-failed` message.
**Stage 5**:
```text
Warning: channel is live, but 3 requested setting(s) were not applied.
Channel ID: 0Mj... Routed to: Default_Queue (00G...)
Steps: ran insert, route, activate, skipped consent
Requested settings:
- Not applicable to Facebook: session idle timeout (15 min) — endUserIdleTimeOut is MIAW-only
- Failed: initial / agent-engaged / idle auto-responses — metadata-deploy-failed: <server message>.
Configure them in Setup → Messaging Settings → this channel for now.
```
Every requested item shows up — nothing is silently dropped.
---
## Worked example: settings on an already-active channel
Prompt: *"Fully configure my existing Facebook channel for page 103663378691289, including the initial auto-response."*
**Stage 1**: preflight finds the channel with `IsActive=true` → `already-active`. `{REQUESTED_SETTINGS}` is non-empty, so instead of returning a no-op, skip Stages 2–4 (`STEPS_SKIPPED=["insert","route","consent","activate"]`) and run **Stage 4.5** for the auto-response. Stage 5 reports the item as configured / not applicable / failed. With an empty `{REQUESTED_SETTINGS}`, the same preflight result returns the plain no-op success envelope.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |