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

100%

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.

100%

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.