/service-de-channel-create

name: service-de-channel-create
description: "**INTERNAL USE ONLY — invoked by `service-de-headless-channel-configure` orchestrator.** Insert an Enhanced messaging `MessagingChannel` record (plus its child `MessagingChannelUsage` as a free server-side side-effect) of any supported type — WhatsApp, LINE, Apple Business Chat, Facebook, or SMS (Text). Given a `{MESSAGE_TYPE}` and the corresponding type-specific inputs, runs the shared preflight → Connect-insert → verify flow and branches only where a type genuinely differs (request body, prerequisites, error classes). Uses the sanctioned `POST /services/data/v{V}/connect/livemessage/channels` Connect REST endpoint — no Aura session, no token extracted into shell state. **Users should always invoke `service-de-headless-channel-configure` instead — it handles insert → route → activate in one flow.** Use this skill when inserting a messaging channel of any type; it replaces the four former per-type creation skills."
metadata:
  version: "1.0"
  minApiVersion: "67.0"
  domains: ["Service"]
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "service-de-channel-activate"
    - "service-de-channel-consent-configure"
    - "service-de-channel-routing-configure"
    - "service-de-headless-channel-configure"
    - "service-de-waba-integrate"

Inserting Messaging Channels

Reference File Index

| Reference file | Load when | | --- | --- | | `references/whatsapp.md` | `MESSAGE_TYPE=WhatsApp` — WABA partnership (Stage 2) + SF-side manage-WABA (Stage 3) prereqs, request body, WhatsApp gotchas. | | `references/line.md` | `MESSAGE_TYPE=Line` — optional token verify, `authDetails` body shape, LINE gotchas. | | `references/apple.md` | `MESSAGE_TYPE=AppleBusinessChat` — empty-config body, Apple-precondition errors, Apple gotchas. | | `references/facebook.md` | `MESSAGE_TYPE=Facebook` — browser OAuth → page-selection flow, Facebook gotchas. | | `references/sms.md` | `MESSAGE_TYPE=Text` — phone-number platform key, present-but-unvalidated `smsProvider`, number-provisioning prerequisite (caller's), SMS gotchas. | | `references/connect-insert.md` | Shared authProviderId lookup + Connect POST + response-classification detail (Stage 4). | | `references/worked-examples.md` | End-to-end traces per type (fresh insert, preflight short-circuit, OAuth). |

What this skill does

Given a `{MESSAGE_TYPE}` and its inputs, creates a `MessagingChannel` record with `PlatformType=Enhanced`, `IsActive=false`. The same server-side path (`LiveMessageSetupServiceImpl.addChannel` → `LiveMessageChannelsUtil.findOrCreateCsotMessagingChannel`) also inserts a `MessagingChannelUsage` row (`DeploymentType=Conversation`, `DeploymentStatus=New` on fresh insert — `Disabled` on a channel that was previously activated then deactivated) — we get it for free.

**One primary path for every type: Connect REST API.** `POST /services/data/v{V}/connect/livemessage/channels` with an org OAuth session managed by `sf api request rest`. Public, sanctioned, live since API v66+. No Aura session, no token extracted into shell state.

**Idempotent** on `(MessagingPlatformKey, MessageType)` — re-firing with the same platform key returns the existing channel's id. This matters because `MessagingChannel` records are not deletable via standard means, so the preflight (Stage 1) is the practical idempotency guard.

All types return the **same envelope shape**, so callers don't branch on type after insert: `{ok, channelId, mcuId, developerName, isActive:false, messageType, messagingPlatformKey, path, created, durationMs}`.

Supported types (the only branch point)

| `{MESSAGE_TYPE}` | Platform key (`messagingPlatformKey`) | Prerequisite (caller supplies) | Body extras | Ref | | --- | --- | --- | --- | --- | | `WhatsApp` | Phone Number ID | `service-de-waba-integrate` (run in Stage 2-3) | `externalAccountId`, `isoCountryCode` | `whatsapp.md` | | `Line` | LINE channel id | LINE id + secret + token (LINE Developers Console) | `authDetails.{client_secret,access_token}` | `line.md` | | `AppleBusinessChat` | Apple BC Account ID (GUID) | Apple BC Account ID (register.apple.com/business-chat) | *(none — empty config)* | `apple.md` | | `Facebook` | Facebook Page ID | *OAuth handled internally* | `authDetails: {}` (OAuth-derived) | `facebook.md` | | `Text` | Phone number / short code | number already provisioned (caller supplies) | `smsProvider` (key required, value may be `""`), `isoCountryCode` | `sms.md` |

Unsupported (would need their own leaf logic, not yet built): `WeChat`, `MsCopilot`, `Alexa`. For these, emit the `unsupported-type` envelope (Stage 0).

When NOT to use this skill

• **End-to-end setup.** If the user wants insert → route → activate, invoke

`service-de-headless-channel-configure` — it orchestrates this skill plus routing, consent, and activation. This skill only handles the insertion step (see Stage 0).

• **The channel already exists and you only want to re-route / activate it.** Skip insertion;

call `service-de-channel-routing-configure` / `service-de-channel-activate` with the existing `channelId`.

Inputs (from caller)

• `{MESSAGE_TYPE}` — one of `WhatsApp`, `Line`, `AppleBusinessChat`, `Facebook`, `Text`.

Case-sensitive (matches the SF picklist). `Text` is the enum value for SMS — there is no `SMS` type.

• `{ORG_ALIAS}` — optional; `sf` CLI target-org alias. Default: `sf config get target-org`.
• `{API_VERSION}` — optional; Connect API version. Default: the org's current API version

(`sf org display --json | jq -r '.result.apiVersion'`). Always use the org's native version to avoid 404s.

• `{CHANNEL_NAME}` — display name shown in Setup → Messaging Settings. Required for

`AppleBusinessChat` (no phone/screen-name fallback); prompted if omitted for others.

Type-specific inputs:

• **WhatsApp:** `{WABA_ID}` (sent as `externalAccountId`), `{PHONE_N