Complete guide to using Telegram Multi-Account Message Sender.
The application provides a graphical desktop client for managing multiple Telegram accounts and sending messages. The main window uses a left navigation rail (Dashboard, Accounts, Campaigns, Templates, Recipients, Testing, Logs, Plugins, Settings, About) with a page title header and stacked content area. Theme and language live under Settings.
- Add multiple Telegram accounts
- Manage account settings
- Monitor account status
- Configure rate limits
- Create message templates
- Use spintax for variations
- Optional AI rewrite / spintax / variations (user-supplied API key)
- A/B testing support
- Template organization
- Add individual recipients
- Import from CSV
- Organize by groups
- Manage recipient lists
- Create campaigns
- Schedule messages
- Monitor campaign status
- Pause/resume campaigns
- Test messages before sending
- Preview message content
- Validate templates
- Check recipient information
- Setup: Configure API credentials and settings
- Add Accounts: Add and authorize Telegram accounts
- Create Templates: Create message templates
- Add Recipients: Add or import recipients
- Create Campaigns: Create and launch campaigns
- Monitor: Track campaign progress and logs
- Open Plugins → Browse Registry.
- Search or filter by type; the catalog source (remote or bundled offline) is shown above the list. Curated downloadable entries include URL Strip, Event Logger, Whitespace Normalize, Failure Counter, Emoji Strip, and Success Counter.
- Select Install on an available entry. The app downloads the plugin into
app_data/plugins/and verifies SHA-256 when the catalog provides it. - Back on the Plugins list, Enable the plugin after reviewing the file. Install never auto-enables third-party code.
- Optional: set
PLUGIN_REGISTRY_URLin Settings /.envto point at a mirror. See Configuration Guide and API Reference.
Sideloading with Load Plugin remains available for local .py files that are not in the catalog.
- Copy
registry/templates/sample_filter_plugin.pyorsample_analytics_plugin.pyand use absolute imports only (from app.core.plugin import …). - Place the installable
.pyunderregistry/plugins/and generate a catalog entry withtelegram-sender plugin-catalog-entry your_plugin.py(optionally--append-to registry/catalog.json). - Validate:
telegram-sender plugin-validate your_plugin.pyandtelegram-sender plugin-validate registry/catalog.json --plugins-dir registry/plugins. - Maintainers: after catalog edits, re-sign with
telegram-sender plugin-catalog-sign … --in-placeand syncapp/plugins/registry/catalog.json. - Open a pull request. See CLI and API.
Monitor account health, campaign status, and recent activity in a browser without giving the companion send/control powers.
- Open Settings → General → Web Companion, keep host
127.0.0.1, optionally set/generate an auth token, then click Start & Open in Browser. - Optional: enable Auto-start with GUI (or
WEB_COMPANION_AUTO_START=true) so launching the desktop app starts the companion in the background — no browser popup; check the Status line in Settings. Closing the app stops a GUI-started companion. - Or run headless:
telegram-sender web-monitor(add--tokenfor non-localhost; see CLI Reference and Configuration). - Dashboard:
http://127.0.0.1:8765/(append?token=when auth is enabled). Live SVG charts auto-refresh every 15s. JSON:/api/status,/api/accounts,/api/campaigns,/api/activity,/api/overview,/api/charts. - Mutating HTTP methods (
POST/PUT/PATCH/DELETE) return 405. Non-localhost binds require a token; prefer localhost behind Caddy/nginx with TLS.
- In
.envor Settings → General → AI Copy Tools, choose a provider preset (openai,azure, oranthropic), setAI_API_KEY, and fill base URL / model (Azure also needs deployment name +AI_AZURE_API_VERSION). See Configuration Guide. - Open Templates → Add/Edit Template.
- Enter draft text, then choose Rewrite with AI, AI → Spintax, or AI variations.
- Review the result before saving. Placeholders like
{name}are preserved when the model follows instructions. - With no API key configured, the buttons show a setup message and make no network calls.
- AI Copy Tools UI strings (Templates buttons, dialogs, and Settings labels) are translated for all 13 app languages — switch language in Settings to see localized labels.
- Install optional cloud packages for Drive/S3:
pip install '.[cloud]'. Dropbox and OneDrive use stdlib HTTP (no extra package). Proton Drive uses the officialproton-driveCLI onPATH(no extra Python package). - Configure Google Drive OAuth (
GOOGLE_DRIVE_CLIENT_ID/GOOGLE_DRIVE_CLIENT_SECRET), S3 credentials (S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY/S3_BUCKET, optionalS3_ENDPOINT_URL/S3_REGION/S3_PREFIX), Dropbox (DROPBOX_ACCESS_TOKEN, optionalDROPBOX_FOLDER), OneDrive (ONEDRIVE_ACCESS_TOKEN, optionalONEDRIVE_FOLDER), and/or Proton Drive (PROTON_DRIVE_CLI,PROTON_DRIVE_FOLDER) in.env— see Configuration Guide. For Proton Drive, also runproton-drive auth loginonce in a terminal. - Open Settings → Cloud Backup and choose the provider (Google Drive, S3-Compatible, Dropbox, OneDrive, or Proton Drive (CLI)).
- Google Drive: click Connect Google Drive and approve access in your browser. S3: click Verify S3 Credentials. Dropbox: click Verify Dropbox Token. OneDrive: click Verify OneDrive Token. Proton Drive: click Verify Proton Drive Session.
- Optionally set an encryption password, then click Backup Now to upload a
.tmas-backup.zip. - Use Refresh List to see remote backups; select one and click Restore Selected Backup to replace the local database (a pre-restore snapshot is saved under
app_data/). - Offline / local restore: use Restore from Local File…, or open a
.tmas-backup.zipvia OS file association (Windowsinstall.ps1/ Linux MIME / macOS UTI after packaging install). No cloud connection required. - Operator handoff (no cloud): click Export for Handoff… for a full
.tmas-backup.zip(database, safe settings, Telethon sessions), or Export Templates/Campaigns… for a selectiveentities.jsonpackage. On restore, entity-only packages prompt for merge (upsert by name) or replace (soft-delete those kinds, then import). CLI:handoff-export --entities …andhandoff-import --mode merge|replace. Desktop remains single-operator; multi-user roles belong to SendGram. Prefer an encryption password for off-machine transfer. - Restart the application after a restore so all components reload the database.
- Cloud restore and list/upload require network access to the selected provider. If you are offline or the provider is unreachable, the app shows a clear warning and does not replace the local database (local-file restore / handoff still work).
From the Dashboard header:
- Click Export CSV… or Export JSON….
- Choose a save path. The export includes a campaign summary table plus flattened metrics (CSV) or a structured overview with per-campaign reports (JSON).
- Empty databases (no campaigns) show a notice instead of writing a file.
Create message variations using spintax syntax:
Hello {John|Jane|Alex}, welcome to {our|my} service!
Schedule campaigns for specific times with timezone support.
Configure rate limits to respect Telegram's limits and prevent account bans.
The Dashboard tab includes an Account Health section that scores each account (0–100) from connection status, success rate, recent 24h errors, warmup progress, and activity.
- Summary cards show average score, healthy accounts, accounts that need attention, and critical/offline counts.
- The table lists worst scores first; select a row for warnings and recommended actions (also available as row tooltips).
- Offline, error, suspended, and inactive accounts get clear status labels and next-step guidance (reconnect, test connection, finish warmup).
- Start with conservative rate limits
- Test messages before sending campaigns
- Monitor account health on the Dashboard and act on warnings before large campaigns
- Use warmup for new accounts
- Keep templates organized
See Examples for practical usage examples.
See Troubleshooting Guide for common issues.