Service De Channel Create

Inserting Messaging Channels

Reference File Index

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)

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_NUMBER_ID} (the platform key — must differ from WABA_ID), {ISO_COUNTRY_CODE} (optional, default US).
• Line: {LINE_CHANNEL_ID} (platform key), {LINE_CHANNEL_SECRET}, {LINE_ACCESS_TOKEN}, {VERIFY_TOKEN_FIRST} (optional, default true).
• AppleBusinessChat: {APPLE_BC_ID} (platform key, GUID).
• Facebook: {PAGE_ID} (optional — OAuth fetches/prompts if absent).
• Text (SMS): {SMS_NUMBER} (the platform key — the phone number / short code string, already provisioned to the org), {SMS_PROVIDER} (sent as smsProvider — the smsProvider key must be present in the body or the insert 400s with "SMS provider is missing", but its value is not validated or stored, so an empty string "" works; default to "" when the caller doesn't supply a provider), {ISO_COUNTRY_CODE} (optional, default US). This skill does not provision the number — the caller must already know their number.

Output (to caller)

Success:

{"ok": true, "channelId": "0Mj...", "mcuId": "0gL...", "developerName": "...",
 "isActive": false, "messageType": "{MESSAGE_TYPE}", "messagingPlatformKey": "...",
 "path": "connect" | "preflight", "created": true | false, "durationMs": 1234}

created: false + path: "preflight" means the row already existed and was returned idempotently.

Failure (shared):

{"ok": false, "kind": "wrong-skill", "correctSkill": "service-de-headless-channel-configure", "hint": "..."}
{"ok": false, "kind": "unsupported-type", "supportedTypes": ["WhatsApp","Line","AppleBusinessChat","Facebook","Text"], "hint": "..."}
{"ok": false, "kind": "missing-input", "missing": ["..."], "hint": "caller must provide all required inputs for this type"}
{"ok": false, "kind": "auth",     "hint": "OAuth token invalid / expired — run 'sf org login web'"}
{"ok": false, "kind": "business", "message": "...", "errorCode": "..."}
{"ok": false, "kind": "transport","status": 500, "message": "..."}
{"ok": false, "kind": "verify-failed", "hint": "Connect returned 201 but follow-up SOQL shows no matching channel"}

Type-specific failure kinds (partnership-blocked, user-declined, waba-manage-failed, meta-precondition for WhatsApp; line-token-invalid for LINE; apple-precondition for Apple; oauth-not-complete, oauth-failed for Facebook) are documented in the per-type reference files.

Stage 0: Enforce orchestrator-only invocation

This skill is INTERNAL USE ONLY. It should only be invoked by the service-de-headless-channel-configure orchestrator.

If the user's original request was to "install", "set up", "create", or "activate" a messaging channel (or any phrasing that implies end-to-end setup), immediately return:

{
  "ok": false,
  "kind": "wrong-skill",
  "hint": "This is an internal insertion skill. For end-to-end channel setup (insert → route → activate), invoke 'service-de-headless-channel-configure' instead with the desired MESSAGE_TYPE.",
  "correctSkill": "service-de-headless-channel-configure"
}

And render to the user:

Error: Wrong skill invoked.

This skill (service-de-channel-create) only handles the insertion step.
For complete channel setup, use: /service-de-headless-channel-configure

That orchestrator runs: insert → configure routing → activate in one flow.

Only proceed to Stage 0.1 if: