Channel Provisioning Protocol

Domain: Communications (Shared Core Domain) Trigger: Operator-initiated channel registration (post-provisioning) Output: Configured channel_accounts with active CPaaS provider connections Sources: communications.md, ADR-003L3 DoD: ✅ Schema | ✅ API | ✅ Edge States — Ready to Code

---

§1 Overview

Channel provisioning is an explicit post-provisioning operator action — ProvisionTenant (ADR-003) seeds notification_templates but does NOT create channel_accounts. Channel registration requires operator action (Meta Business Verification, SES domain verification) that the system cannot automate at signup.

The Workspace UI shows a "Complete your communications setup" onboarding checklist. Seeded notification_templates reference channels that do not yet exist — the notification pipeline defers template activation until the matching ChannelAccount reaches ACTIVE.

---

§2 ChannelAccount Lifecycle State Machine

stateDiagram-v2
    [*] --> PENDING_VERIFICATION : registerChannel
    PENDING_VERIFICATION --> ACTIVE : Provider verification completes
    PENDING_VERIFICATION --> SUSPENDED : Verification failed / timed out (30d)
    ACTIVE --> SUSPENDED : Manager action or provider revocation
    ACTIVE --> REVOKED : Provider permanently bans account
    SUSPENDED --> ACTIVE : Re-verification or manager reactivation
    REVOKED --> [*] : Terminal — must register new account

From	To	Trigger	Side Effects
—	PENDING_VERIFICATION	registerChannel Hasura Action	Creates channel_accounts + operator_integrations (PENDING). Initiates provider verification.
PENDING_VERIFICATION	ACTIVE	Provider verification completes	operator_integrations.status → CONNECTED. Pipeline can dispatch. change_event (CONFIG).
PENDING_VERIFICATION	SUSPENDED	Verification failed/timed out	operator_integrations.status → FAILED + error_message.
ACTIVE	SUSPENDED	Manager action or provider revocation detected	operator_integrations.status → DISCONNECTED. Pipeline skips channel → fallback chain.
SUSPENDED	ACTIVE	Re-verification or manager reactivates	operator_integrations.status → CONNECTED.
ACTIVE	REVOKED	Provider permanently bans account	Terminal. operator_integrations.status → DISCONNECTED. Must register new account.

Suspension detection:

• WhatsApp: channel_health_check Hasura Cron Trigger (daily, 03:00 UTC) polls Meta WABA status.
• Email: SES accountSendingPaused SNS notification → auto-suspend.

---

§3 WhatsApp Registration Flow (Meta Embedded Signup)

Phase 1 uses Meta's Embedded Signup — a JavaScript SDK handling Facebook Login, business verification, and WABA creation in an iframe.

sequenceDiagram
    participant UI as Workspace UI
    participant Meta as Meta Embedded Signup
    participant API as NestJS registerChannel
    participant DB as PostgreSQL

    UI->>Meta: FB.login() (iframe)
    Meta-->>UI: waba_id, phone_number_id, short_lived_token
    UI->>API: registerChannel(WHATSAPP, credentials)
    API->>Meta: Exchange short-lived → long-lived token
    API->>Meta: POST /{waba_id}/subscribed_apps (per-WABA webhook override)
    Meta->>API: GET /webhooks/meta/{tenant_id}?hub.verify_token=...
    API-->>Meta: hub.challenge (200 OK)
    API->>DB: INSERT channel_accounts (PENDING_VERIFICATION)
    API->>DB: INSERT operator_integrations (PENDING)
    API-->>UI: { channel_account_id, status }

Steps:

1. Operator opens Workspace Settings → Communications → Add Channel → WhatsApp.
2. Meta Embedded Signup launches (FB.login() with whatsapp_business_management permissions).
3. Operator completes flow → Meta returns waba_id, phone_number_id, short-lived token.
4. Frontend calls registerChannel with the credentials.
5. Handler: exchange token → generate webhook_verify_token → subscribe to Meta webhooks via POST /<WABA_ID>/subscribed_apps (WABA-level override, not app-level /{app_id}/subscriptions) → encrypt secrets → INSERT both tables → poll Meta Business Verification status.

NOTE

Busflow Meta App: All tenants share one Busflow-owned Meta App (BSP model). app_id and app_secret are platform-level constants stored in provider_config for worker convenience.

WARNING

Blocking prerequisite: The Busflow Meta App must pass Meta App Review for whatsapp_business_management and whatsapp_business_messaging before any tenant can provision WhatsApp.

---

§4 Email Registration Flow (SES Domain Verification)

Operator adds DNS records (DKIM, SPF/DMARC) to prove domain ownership.

Steps:

1. Operator opens Add Channel → Email, enters domain (e.g., reisen-mueller.de).
2. Frontend calls registerChannel with domain and sender email.
3. Handler: create SES domain identity → enable DKIM → create Configuration Set → create SNS topics + subscription → return DNS records.
4. Operator adds DNS records at domain registrar.
5. ses_verification_check Cron Trigger (every 15 min) polls SES verification status.
6. On success → ACTIVE. On 30-day timeout → SUSPENDED.

DNS Record Display UI: Panel with copy-to-clipboard buttons, per-record status indicators (⏳/✅/❌), and "Verify Now" button.

NOTE

SES Sandbox: Busflow's AWS account must promote out of SES Sandbox before any tenant sends production emails.

---

§5 SMS Registration (Platform-Managed)

Phase 1: Platform-managed, not operator-provisioned. DACH Sender ID registration requires per-country carrier pre-registration — unsuitable for self-service.

• Busflow registers a platform-wide Sender ID ("Busflow") with DACH carriers via SNS.
• All tenants share this Sender ID.
• registerChannel for SMS creates the row with status = ACTIVE immediately.
• provider_config stores platform-level SNS config.

Phase 2: operators can register their own Sender ID (1–3 week carrier approval).

---

§6 Hasura Action Contracts

registerChannel

Property	Type	Required	Description
Input
channel_type	String	✅	WHATSAPP, EMAIL, SMS
display_name	String	✅	Operator-editable label
sender_identity	String	✅	Canonical sender identifier
whatsapp_config	Object	❌	Required if WHATSAPP (§3)
email_config	Object	❌	Required if EMAIL (§4)
Output
channel_account_id	UUID	✅	Created ChannelAccount ID
status	String	✅	PENDING_VERIFICATION or ACTIVE
dns_records	Object[]	❌	EMAIL only: DNS records to add
Errors
CHANNEL_ALREADY_EXISTS			Tenant has existing account for this channel type
PROVIDER_ERROR			Meta/SES API call failed
VALIDATION_ERROR			Invalid input

Authorization: MANAGER role only.

updateChannelConfig

Updates operator-editable fields. Does NOT allow changing channel_type or secrets (re-registration required).

Property	Type	Required	Description
channel_account_id	UUID	✅	Target account
display_name	String	❌	Updated label
sender_identity	String	❌	Updated sender (re-verification for Email)
reply_to_email	String	❌	Email only

Authorization: MANAGER role only.

testChannel

Sends a test message to verify end-to-end connectivity.

Property	Type	Required	Description
channel_account_id	UUID	✅	Channel to test
test_recipient	String	✅	Phone (E.164) or email

Authorization: MANAGER or DISPATCHER.

suspendChannel / reactivateChannel

Property	Type	Required	Description
channel_account_id	UUID	✅	Target account
reason	String	✅	Logged in change_events

Side effects (suspend): Pipeline skips channel. Queued messages → FAILED with failed_reason = 'channel_suspended'. Fallback chain activates.

Authorization: MANAGER role only.

---

§7 Meta Webhook Setup & Verification

NOTE

WABA-level override: This section covers webhook setup via POST /<WABA_ID>/subscribed_apps. The per-tenant callback URL (/api/webhooks/meta/{tenant_id}) receives both inbound messages and delivery status callbacks. See notification-pipeline-protocol.md §8 for the delivery webhook handler spec.

During registration (automatic):

1. Handler calls POST /<WABA_ID>/subscribed_apps with tenant-specific override_callback_url and verify_token. This is a WABA-level override — it does NOT overwrite the app-level subscription. Each tenant's WABA independently routes to its own callback URL.
2. Meta sends GET /api/webhooks/meta/{tenant_id}?hub.mode=subscribe&hub.verify_token={token}&hub.challenge={challenge}.
3. Controller: extract tenant_id → load channel_accounts → compare webhook_verify_token → respond with hub.challenge or HTTP 403.

Runtime signature verification (every delivery):

1. Meta sends POST /api/webhooks/meta/{tenant_id} with X-Hub-Signature-256.
2. Handler computes HMAC-SHA256(app_secret, body) → compare.
3. Match → process. Mismatch → HTTP 401, log security alert.

IMPORTANT

Shared Meta App Secret: All tenants share one app_secret. Tenant isolation relies on WABA-level scoping (each WABA receives webhooks for its own phone number only).

---

§8 operator_integrations ↔ channel_accounts Sync Contract

Two tables, two schemas, one business concept. Writes happen atomically within a single transaction.

Event	channel_accounts	operator_integrations
Registered	INSERT PENDING_VERIFICATION	INSERT PENDING
Verification succeeds	→ ACTIVE	→ CONNECTED
Verification fails	→ SUSPENDED	→ FAILED + error_message
Manager suspends	→ SUSPENDED	→ DISCONNECTED
Manager reactivates	→ ACTIVE	→ CONNECTED
Provider revokes	→ REVOKED	→ DISCONNECTED
Manager deletes	DELETE	→ DISCONNECTED

NOTE

Cross-schema write justification: Controlled exception to "contexts communicate via events." Channel provisioning is an administrative configuration action (infrequent, operator-initiated) that must be atomic. Async sync would create consistency gaps in the Workspace UI.

---

§9 operator_integrations — CPaaS Types

integration_type	Description	Provisioned By
META_WHATSAPP	WhatsApp via Meta Cloud API	registerChannel (operator)
AWS_SES	Email via Amazon SES	registerChannel (operator)
AWS_SNS	SMS via Amazon SNS	registerChannel (platform-managed Phase 1)

Config shapes live in schema-backoffice.md §operator_integrations.