Architecture

Request Flow

┌──────────┐    Webhook     ┌──────────────────────────────┐    insert    ┌─────────────┐
│ Platform │ ──────────────▶│ /api/channels/[provider]/     │ ──────────▶│ agent_tasks  │
│ (TG/DC/..)│  + secret     │           webhook             │             │             │
│          │◀──────────────│  verify → find channel by      │◀────────── │  space =     │
│ ✅ reply  │   Bot API     │  secret → create task in      │   return    │  default     │
│          │               │  channel's defaultSpaceId      │             │  space       │
└──────────┘               └──────────────────────────────┘             └─────────────┘

Key Design Decisions

• User-scoped — channels belong to a user, not a space. Each has a defaultSpaceId for task creation.
• Polymorphic adapters — ChannelAdapter interface with verify, registerWebhook, removeWebhook, parseMessage, reply. Adding a provider = one adapter file + register in registry.
• Shared package — core schema, types, adapter interface, and all adapters live in packages/share-domains/channels/ for reuse across apps.
• Webhook routing — each channel has a unique webhookSecret; platforms send it in provider-specific headers.
• Always 200 — webhook handler always returns 200 to prevent platform retries.
• Credentials server-side only — bot tokens are never exposed in API responses (VO only returns username + status).

Adding a New Provider

1. Add the provider name to CHANNEL_PROVIDERS in packages/share-domains/channels/schema/chat-channels.ts
2. Create packages/share-domains/channels/logic/adapters/{provider}.ts implementing ChannelAdapter
3. Register it in packages/share-domains/channels/logic/registry.ts
4. Add the provider config to PROVIDER_CONFIG in the UI component
5. Add documentation in content/docs/{lang}/chat-channels/{provider}.mdx