Bridges Overview

A bridge is a workspace-facing adapter between Compozy sessions and an external platform. The Compozy source repository contains in-tree providers for Slack, Discord, Telegram, WhatsApp, Microsoft Teams, Google Chat, GitHub, and Linear. They are not embedded in the released compozy binary: build and install the provider from a trusted source checkout before configuring its bridge instances. The bridge instance stores the operator-owned configuration, while the provider extension owns webhook validation, message normalization, and outbound delivery.

That split keeps Compozy responsible for sessions, routing, persistence, and delivery bookkeeping while letting each platform adapter speak the platform API directly.

In this section

Choose a provider

Start with Bridge setup, which links to one dedicated guide per provider. A provider is complete only after configuration, runtime, public transport, inbound route, and real outbound-delivery proofs all pass.

Runtime model

The provider catalog is dynamic. GET /api/bridges/providers returns installed extensions that provide bridge.adapter, including disabled providers. Inspect each descriptor's enabled, state, and health before creating an instance. The source repository contains provider manifests for Slack, Discord, Telegram, WhatsApp, Microsoft Teams, Google Chat, GitHub, and Linear. The setup section covers every in-tree provider and calls out mode-dependent credentials explicitly.

Message flow

Adapter architecture

The bridge adapter runs as an extension subprocess. During initialization, Compozy gives it the bridge instances assigned to that extension and a Host API surface. The adapter then:

1. Resolves bridge secret bindings from the daemon-provided cache.
2. Starts webhook listeners for configured bridge instances.
3. Verifies incoming platform requests before ingestion.
4. Converts platform payloads into normalized bridge envelopes.
5. Reports bridge state back to Compozy as ready, degraded, auth_required, or error.
6. Delivers response events back to the platform API and acknowledges delivery to Compozy.

Compozy does not parse provider webhook payloads in the daemon. The daemon accepts the normalized envelope only after the provider extension authenticates it and confirms that the bridge instance is enabled for that extension.

Bridge instance format

Bridge instances are persisted runtime records. They are created through the bridge API or the compozy bridge create command, not through config.toml.

{
  "scope": "workspace",
  "workspace_id": "ws_8f33a913d23c4fd1",
  "platform": "slack",
  "extension_name": "slack",
  "display_name": "Slack support",
  "enabled": false,
  "status": "disabled",
  "dm_policy": "allowlist",
  "routing_policy": {
    "include_peer": false,
    "include_thread": false,
    "include_group": true
  },
  "provider_config": {
    "webhook": {
      "public_url": "https://bridge.example.com/slack/support",
      "listen_addr": "127.0.0.1:18081",
      "path": "/slack/support"
    },
    "dm": {
      "allow_user_ids": ["U0123456789"]
    }
  },
  "delivery_defaults": {
    "group_id": "C0123456789",
    "mode": "direct-send"
  }
}

Package-managed instances can be created by extension bundles. Those records report source: "package" and reject direct spec mutation through the generic update API.

Supported provider slots

Bind each slot to a Compozy-managed vault secret before enabling the bridge. The API accepts the plaintext only through the write-only secret_value field and never returns it:

BRIDGE_ID=brg_123

printf '%s' "$SLACK_BOT_TOKEN" | compozy bridge secret-bindings put "$BRIDGE_ID" bot_token \
  --secret-ref "vault:bridges/$BRIDGE_ID/bot_token" \
  --kind token \
  --secret-value-stdin

The reference must be scoped to the edited bridge: vault:bridges/<bridge>/<slot>. Restart or enable the bridge after changing a binding so the provider receives fresh launch material.

Bridge Vault refs are visible as redacted metadata through the Vault page, compozy vault list --namespace bridges, and /api/vault/secrets?namespace=bridges. The plaintext secret_value is accepted only on write.

Operational states

Bridge health is exposed with each bridge payload and through the bridge health stream. It includes route count, delivery backlog, dropped delivery count, delivery failures, auth failures, last success, last error, and degradation metadata.

Target directory

Bridge adapters can report platform targets such as channels, rooms, users, groups, and threads. Adapters that do not implement native target enumeration use Compozy's fallback snapshot from the bridge instance's operator-declared delivery defaults. The daemon validates snapshots, writes bridge_target_directory, and records the latest successful refresh time. The directory refreshes when an extension runtime connects and then every five minutes while that runtime remains connected.

The in-tree provider walkthroughs use operator-declared delivery defaults for target snapshots. Native platform discovery such as Slack conversations.list is not part of the v1 target-directory contract.

Each target stores the provider-derived immutable route, display name, normalized lookup key, optional qualifier, type, capabilities, updated_at, and last_seen_at. Missing targets are not deleted during refresh; their last_seen_at remains the last time the provider saw them so operators can distinguish stale but known targets from new unknown names.

Use the target APIs before wiring notification presets or explicit outbound targets:

compozy bridge targets brg_123 --query launch -o json
compozy bridge resolve brg_123 "launch room" -o json

The HTTP/UDS equivalents are GET /api/bridges/:id/targets and POST /api/bridges/:id/resolve. Resolve returns a structured diagnostic for ambiguous or unknown names instead of selecting a candidate silently.

Notification suppression

Each bridge instance has a live notification_suppress flag. When it is true, the common bridge notification delivery path suppresses notification deliveries for that bridge and returns a deterministic suppression result to the caller. Notification presets treat suppression as a terminal skip and advance their cursor, so a muted bridge does not replay the same preset event forever. Task bridge subscriptions and direct notifiers use the same common check.

Use suppression for planned bridge maintenance or noisy downstream systems. It is not a replacement for disabling the bridge: disabled or unhealthy bridges reject delivery as unavailable and leave cursors unadvanced for retry, while suppression intentionally records that the event was skipped for that bridge.