One wrapper, every channel.

Section 01 · the problem

A dozen channels, or one model with a dozen edges?

A naive omnichannel build writes WhatsApp code, then Telegram code, then Instagram code — each with its own contact lookup, its own conversation logic, its own reply path. By channel five the codebase is a museum of near-duplicates.

We studied how mature omnichannel inboxes are built and found the real lever isn't the integrations. It's that every channel collapses into one canonical model behind exactly two seams: an inbound normalizer and an outbound sender. Everything else — contacts, conversations, messages, attachments — is shared.

Our middleware already had the canonical storage. What it lacked was the wrapper. RFC 2210 adds it: a stateless driver engine, a canonical message representation, per-config webhook rotation, and a business-owner Channel Manager — so a new channel is one driver file plus one factory case, and nothing else changes.

Section 02 · architecture

The wrapper sits between the vendors and the canonical store.

Drivers are stateless. Per-config credentials are passed on every call, so one driver instance serves every workspace that uses that channel — and the whole engine is unit-testable without a database.

flowchart TB
  subgraph V["Vendors"]
    WA["WhatsApp Cloud"]
    TG["Telegram"]
    IG["Instagram"]
    EM["Email / SMS / ..."]
  end

  subgraph ENGINE["Common Channel Wrapper  (internal/channels/driver)"]
    FAC["Factory  New(kind, provider)"]
    DRV["Channel driver
Verify · Parse · Send"]
    CAP["Capability descriptor"]
    FAC --> DRV
    DRV --- CAP
  end

  CIR["Message Wrapper (CIR)
InboundEvent / OutboundEnvelope"]

  subgraph CANON["Canonical store (already existed)"]
    ID["user_identities
(contact_inbox)"]
    SES["chat_sessions
(conversation)"]
    MSG["messages + channel_envelopes"]
  end

  subgraph CLIENTS["Surfaces"]
    WS["Workspace
operator console"]
    OU["ouchat
customer app"]
  end

  V -->|webhook| FAC
  DRV --> CIR --> CANON
  CANON -->|realtime| WS
  CANON -->|realtime| OU
  WS -->|reply| DRV --> V

Section 03 · the canonical model

We already had the hard part.

The canonical entities mapped almost 1:1 onto tables we'd already shipped. The wrapper slots underneath features most inboxes lack — takeoff codes, channel health, fallback chains.

Section 04 · inbound

From a signed webhook to a conversation.

One ingress — /api/v1/webhook/:configId — for every channel. The config id is an immutable UUID, so renaming a workspace never breaks a vendor's pasted URL. Verification is per-config; persistence reuses already-audited services.

sequenceDiagram
  participant Vendor
  participant WH as Unified Webhook
/api/v1/webhook/:id
  participant DR as Channel Driver
  participant SK as Persist Sink
  participant DB as Canonical Store

  Vendor->>WH: POST signed payload
  WH->>DR: Verify(signature, creds)
  alt signature invalid
    WH-->>Vendor: 200 (drop + log)
  else valid
    WH->>DR: Parse(raw) → InboundEvent[]
    loop each event
      WH->>SK: HandleEvents
      SK->>DB: dedup SET NX (channel, provider_msg_id)
      SK->>DB: ResolveIdentity → user + identity
      SK->>DB: published agent → ResolveSession
      SK->>DB: PersistMessage (+ envelope, realtime)
    end
    WH-->>Vendor: 200
  end

Idempotency is a Redis SET NX on (channel, provider_msg_id) — webhooks are at-least-once. Signature verification is the real gate: Meta HMAC-SHA256 over the body with the app secret, Telegram's secret-token header, LINE's base64 HMAC. A failed signature is dropped and logged, never surfaced.

Section 05 · outbound

A template-method with guards, then the driver.

Every outgoing message runs the same guards before a driver ever sees it — is it outgoing, not private, not an echo of an inbound message? Then the capability descriptor decides: free-form reply, or template-only.

flowchart LR
  A["Agent / AI persists
outgoing message"] --> D["Dispatcher"]
  D --> G{"Guards"}
  G -->|private / echo| X["skip"]
  G -->|window open| S["driver.Send(text/media)"]
  G -->|window closed| T["require approved template"]
  S --> W["write provider id
+ status"]
  T --> W
  S -->|error| F["status=failed
+ health record"]

Section 06 · capabilities

One descriptor gates the backend and both UIs.

The capability struct is the single source of truth. It gates the outbound path (window → template, attachment limits) and drives what the operator console and ouchat render — the same composer affordances, the same "window expired" banner. That's what "same behaviour everywhere" means in practice.

Section 07 · security

The URL is immutable. The secret rotates.

The inbound URL is keyed on the config UUID, so it never changes — a vendor console never breaks. The signing secret rotates on demand.

On rotation the current secret moves to a previous slot and a fresh one is generated. Verification accepts either for a 48-hour grace window, so an in-flight webhook is never dropped mid-rotation. Credentials are sealed with the shared AES-GCM envelope (AAD-bound to app_channel_configs · credentials) and never returned over the API — reads expose only the verify token and the signing secret's last four characters.

Section 08 · the surface

The business owner's journey, end to end.

The Channel Manager lives in the workspace (the business's own admin). It reuses the same channel-config service the platform admin uses — they differ only by scope, never by code path.

flowchart LR
  subgraph ENABLE["Enablement"]
    C1["Pick channel
from catalog"] --> C2["Authenticate
OAuth / key / token"]
  end
  subgraph CONNECT["Connect"]
    C2 --> C3["Webhook URL
+ verify token"] --> C4["Rotate secret
(48h grace)"]
  end
  subgraph OPERATE["Operate"]
    C4 --> C5["Assign AI agent"] --> C6["See conversations
AI vs human"] --> C7["Respond"]
  end
  subgraph HANDOFF["Handoff"]
    C7 --> C8["Human takeover"] --> C9["Switch channel
(takeoff)"]
  end