# Telegram Safe Campaign Launchpad Design

Date: 2026-05-27

## Goal

Add a manual, permission-guarded Telegram campaign launchpad that lets operators preview a limited audience and queue template-based Telegram notifications safely, without building a full automation engine.

## Scope

This slice adds:

- one admin page under `/admin/telegram/campaigns`
- one launch form with:
  - `template_key`
  - `locale`
  - `campaign_key`
  - `audience_type`
  - limited audience filters
- preview of masked audience rows before queue
- queue-only execution into `telegram_notifications`
- audit logging for preview and queue actions

This slice does not add:

- drip campaigns
- scheduled send orchestration
- CRM/enrollment/finance mutation
- auto segmentation beyond the three explicit audiences

## Audiences

Phase-1 audiences:

- `verified_accounts`
- `recently_active_accounts`
- `campaign_matched_accounts`

Audience filters:

- `recent_days` for recently active accounts
- `source_campaign_key` for campaign-matched accounts

## Safety Model

- permission: `telegram.campaigns.manage`
- audience includes verified Telegram accounts only
- preview masks Telegram IDs and PII by default
- hard batch cap per queue action
- queue uses idempotency keys derived from account + template + locale + campaign
- re-running the exact same launch skips duplicates instead of creating second sends
- audit log written for preview and queue

## Architecture

New Telegram admin layer:

- `CampaignsPage`
- `ResolveTelegramCampaignAudienceAction`
- `PreviewTelegramCampaignAudienceAction`
- `QueueTelegramCampaignLaunchAction`

The launchpad reuses:

- `telegram_accounts`
- `message_templates`
- `telegram_notifications`
- `QueueTelegramNotificationAction`
- `SendTelegramPlatformNotificationJob`

## Payload Strategy

Queued payloads should carry:

- `locale`
- `campaign_key`
- `audience_type`
- `student_name`
- `full_name`
- `telegram_username`
- `platform_url`
- `payments_url`
- `webinars_url`
- `support_url`

This keeps templates generic enough for safe manual campaigns without assuming event-, payment-, or attendance-specific facts.

## UX

The page should show:

- launch form
- audience summary
- masked preview rows
- queue result summary
- brief guardrails note

## Tests

- authorized operator can open Telegram campaigns page
- preview returns masked audience rows
- queue creates pending notifications for verified audience only
- duplicate queue is prevented for same launch fingerprint
- campaign-matched audience respects source campaign filter
- unauthorized users are blocked