Channel Connections

How users connect external notification channels (Telegram, Discord) to their account.

Email Channel

Email is always connected via the user's account email. No connection flow needed.

Telegram Channel

Connection Flow

User clicks "Connect Telegram"
         │
         ▼
┌────────────────────────┐
│ Generate unique token  │  ← 15 min expiry, cryptographically random
│ Store in DB            │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Return deep link:      │
│ t.me/Bot?start=TOKEN   │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ User clicks link       │  ← Opens Telegram app (mobile/desktop)
│ Opens Telegram         │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ User sends /start      │  ← Telegram sends webhook to our API
│ to bot                 │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Webhook handler:       │
│ 1. Validate token      │
│ 2. Mark token as used  │
│ 3. Store chat_id       │
│ 4. Send confirmation   │
└────────────────────────┘

Deep Link Behavior

Use https://t.me/ format, not tg:// which doesn't work in browsers.

Webhook Handler

The webhook receives Telegram /start commands. For outbound-only notification delivery, use raw fetch() to the Telegram Bot API — no framework needed:

// Outbound notification delivery — zero dependencies
await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ chat_id: chatId, text: message, parse_mode: 'HTML' })
});

For the webhook handler (inbound /start command processing), use grammY only if you need middleware, session state, or complex command routing. For simple token validation, raw request parsing is sufficient.

Verification Token

Credential Storage

No tokens stored - Telegram uses chat_id only.

Discord Channel

OAuth2 Flow

User clicks "Connect Discord"
         │
         ▼
┌────────────────────────┐
│ Generate CSRF state    │  ← Store in HttpOnly cookie
│ Build OAuth URL        │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Redirect to Discord:   │
│ authorize?client_id=   │
│ &redirect_uri=         │
│ &scope=identify        │
│ &state=CSRF            │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ User approves on       │
│ Discord                │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Discord redirects:     │
│ /callback?code=&state= │
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│ Callback handler:      │
│ 1. Validate CSRF state │
│ 2. Exchange code       │
│ 3. Fetch /users/@me    │
│ 4. Store credentials   │
│ 5. Redirect + toast    │
└────────────────────────┘

Required OAuth2 Scopes

Note: The identify scope does NOT grant DM permission. See limitation below.

Critical Limitation: DMs Require Mutual Server

Discord has no OAuth2 scope for sending DMs to users without a mutual server.

Recommendation: If implementing Discord, require users to join a support/community server, then the bot can DM server members.

Token Management

Token Refresh Strategy

Before sending notification:
         │
         ▼
┌────────────────────────┐
│ Check token_expires_at │
└──────────┬─────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
 Valid        Expiring/Expired
    │             │
    │             ▼
    │      ┌────────────────┐
    │      │ POST /token    │
    │      │ grant_type=    │
    │      │ refresh_token  │
    │      └───────┬────────┘
    │              │
    │       ┌──────┴──────┐
    │       ▼             ▼
    │    Success       Failed
    │       │             │
    │       │             ▼
    │       │      Mark inactive
    │       │      Notify user
    │       │
    └───────┴──────────────┐
                           ▼
                   Send notification

Credential Storage

Token Encryption

Channel Health Monitoring

Failure Detection

Inactive Channel UI

When a channel becomes inactive:

┌─────────────────────────────────────────┐
│ Telegram                                │
│                                         │
│ ⚠️ Disconnected                          │
│ "Bot was blocked"                       │
│                                         │
│ [Reconnect]                             │
└─────────────────────────────────────────┘

Disconnection Flow

User-Initiated Disconnect

Note: We soft-delete (set is_active = false) rather than hard-delete to:

• Preserve audit trail
• Allow easy reconnection
• Prevent duplicate chat_id/user_id linking

Cleanup

Background job removes records where is_active = false and unlinked_at < NOW() - 90 days.

Security Considerations

Related

• ./settings.md - UI for connection management
• ./schema.md - Database tables for credentials
• ./routing.md - How providers use credentials
• ../auth.md - OAuth2 patterns