Everything you need to know

Download & install

The app is portable on Windows and drag-and-drop on macOS. No dependencies, no admin rights.

Windows

macOS

Where the data lives

Telegram API setup

Every Telegram client needs api_id and api_hash — free official credentials from Telegram. Getting them takes about 3 minutes.

Activation & plans

Three plans, one activation window. Switch at any time by entering a new key.

Plans at a glance

Activating a key

Offline grace period

The app checks the license every 6 hours. If there's a network problem, it continues working from the cached state for up to 30 days (until the last verified end date). You'll see a grey Offline badge on the license card, but no functionality is lost.

Where to see the status

• Sidebar card — plan name, days left, end date
• Settings → License — same info in the settings page
• Top banner — visible if license is missing or expired

Accounts

The Accounts page is your home base. Everything else — recipients, ads, campaigns — belongs to the currently selected account.

The account grid

Each account is a card showing:

• Name and initial badge
• Status — Authorized (green) or Not authorized (grey)
• User info — the Telegram display name and @username
• Phone, Proxy, and current session status

The account you're currently working with is marked with a violet border and a CURRENT badge in the top-right corner.

Toolbar

Card actions

Adding a new account

QR / SMS authorization

Two methods. QR is faster and doesn't need a phone field — SMS is a fallback.

Choosing a method

Click Authorize on any account. A dialog opens with two options:

• QR code — recommended. Requires only API ID + API Hash.
• SMS code — requires a phone number in the account settings.

If the phone is empty, the SMS option is disabled with a hint.

QR login

SMS login

Session health check v4.0

The app keeps your Telegram sessions alive without you having to babysit them.

How it works

On app startup and at the configured interval, the app walks through every account and verifies the session is alive. It's a fast operation — one request per account. No QR or SMS, sessions are loaded from data/sessions/.

Checks run in a background thread pool (up to 3 accounts in parallel), so the interface stays responsive.

Status indicators

In the Accounts page, each card gets a colored dot next to its name:

• 🟢 Authorized — session alive, ready to work
• 🔴 Not authorized — session dead, needs QR re-authorization
• 🟠 Unreachable — network problem (no internet, proxy dead). Session is probably alive — we just couldn't verify
• ⚪ Not configured — account has no API credentials
• 🟣 Checking — check in progress

Enabling and configuring

Go to Settings → Session health check:

Manual check

Click Check sessions in the toolbar on the Accounts page. Progress is visible via the dot indicators; the button shows checking… X/Y.

Re-authorization queue

When dead sessions are found, the app offers to re-authorize them one by one:

1. A prompt appears: "Found N dead sessions. Re-authorize all now?"
2. Click Yes — a QR login window opens for the first dead account
3. Scan the QR with your phone. When that account authorizes, the next QR opens automatically
4. The process continues until the queue is empty
5. A summary toast shows: Re-auth finished: N successful, M failed

Account health monitor v4.0

A risk indicator per account, based on real sending activity from the last 24 hours.

Opening it

On any account card, click the shield icon. A modal opens with health data for that account.

What you'll see

Risk levels

Recommendations

Click Recommendations in the modal for a checklist based on the current data. For example:

• If PEER_FLOOD > 0 — pause this account for 24–48 hours
• If floods are frequent — increase delays between messages
• If sent > 100/24h — reduce daily volume
• Green accounts get a "You're good, keep doing what you're doing"

Recipients

Groups, channels and contacts available for the current account, laid out in three columns.

Toolbar

Three columns

• Groups — chats and supergroups where you have posting rights
• Channels — broadcast channels you admin
• Contacts — users you can DM

Working with items

• Checkbox — select individual recipients
• Checkbox in header — select / deselect all in this column
• Delete button on hover — remove the single recipient from the local list (doesn't affect Telegram)
• Add + — manually add a single recipient (typing the exact name)
• Remove selected — remove all checked recipients

Selection actions bar

When at least one item is selected, a violet action bar appears above the columns with:

• Add to group — move the selection into a named group
• Remove from group — visible only when a group filter is active
• Delete — remove selected recipients entirely
• Clear selection — uncheck everything

Recipient groups v4.0

Named collections of recipients — like "Main", "VIP", "Test" — for one-click selection in ads.

Creating a group

Managing groups

In the Manage groups dialog you can:

• Rename a group — pencil icon
• Delete a group — trash icon. The recipients themselves stay in your list; only the group membership is removed.
• See the member count next to each group

Filtering the Recipients view

Use the group filter dropdown on the toolbar to view only members of a specific group. Options:

• All recipients — show everything
• Without group — only recipients not in any group
• Any specific group name

Selecting a group in the ad editor

Open any ad → Recipients tab. Above the three columns you'll see a row of group chips:

• ○ name — 12 — nothing selected (12 available)
• ◐ name — 5/12 — partially selected
• ✓ name — 12 — fully selected (green)

Click a chip to toggle the whole group. Click again to deselect everything in that group.

Import CSV / Excel / JSON v4.0

Bulk-load recipient lists from spreadsheets, JSON dumps, or a CSV exported from another app.

Supported formats

• CSV — auto-detects delimiter (;, , or tab)
• Excel — .xlsx and .xlsm with an interactive column-mapping dialog
• JSON — either a list of objects or a dict with group/channel/contact keys

CSV format

Two or three columns: type, name, and optional group.

type;name;group
group;Marketing chat;Main
channel;@my_channel;Main
contact;John Smith;
group;Test chat;Test

Type accepts synonyms in English and Russian:

• group, groups, группа, группы
• channel, channels, канал, каналы
• contact, contacts, контакт, контакты, user, users

JSON format

Two accepted shapes:

[
  { "type": "group",   "name": "Marketing chat", "group": "Main" },
  { "type": "channel", "name": "@my_channel",   "group": "Main" }
]

Or grouped by type:

{
  "group":   ["Marketing chat", "Test chat"],
  "channel": ["@my_channel"],
  "contact": ["John Smith"]
}

Excel column mapping

When you import an .xlsx file, a mapping dialog appears:

• Type column — which column holds group/channel/contact
• Name column — which column holds the actual recipient name
• Group column — optional named group to assign each recipient to

The app auto-guesses based on header names ("type", "name", "group", and their Russian equivalents). A live preview shows the first 4 rows as they will be parsed.

Import preview

After parsing you'll see a summary:

• New — how many new rows will be added
• Duplicates — how many already exist in your list
• Errors — parse problems, with line numbers
• Detected groups — group names found in the file

Merge vs Replace

• Merge — appends new recipients, skips duplicates, leaves existing ones untouched
• Replace — wipes the current list and uses only what's in the file (an extra confirmation dialog appears)

Exporting to CSV

Click Export CSV on the toolbar. The file is saved with:

• UTF-8 BOM encoding — Excel opens non-ASCII text correctly
• Semicolon delimiter
• Optional group column listing all recipient groups the item belongs to

Default filename: recipients_AccountName_20261016_143052.csv.

Ads overview

The Ads page lists all your scheduled messages for the current account and gives live control over each one.

Layout

Two-panel split:

• Left — list of ads with a running/paused/stopped marker
• Right — details for the selected ad

Markers in the list

• ▶ — running
• ⏸ — paused
• ⏹ — stopped

Toolbar actions

Details panel

Shows the selected ad's content summary, interval, time window, recipient counts, delays, and — while running — a live progress bar.

Control buttons:

• Start — begin sending
• Pause / Resume — temporarily halt without losing state
• Stop — cancel completely (running cycle interrupts immediately)
• Edit, Duplicate, Delete

Creating a new ad

Click New ad to open the editor. The editor has four tabs:

1. Content — text, media, rotation, chains
2. Recipients — groups, channels, contacts, forum topics
3. Schedule — interval, time window, days, delays, auto-stop
4. Advanced — send limit, templates

Each tab is covered in its own section below.

Ad editor — Content

Compose the message. Three modes: single message, content rotation, and message chains.

Mode 1 — Single message

The default mode. Fill in the message text and optionally attach media. Variables are supported (see below).

Mode 2 — Content rotation

Enable Use rotation to define multiple variants (see the dedicated rotation section).

Mode 3 — Message chains

Enable Message chains to switch to multi-step scenarios (see the dedicated chain section).

Message field

Supports multiline text, HTML formatting, and dynamic variables:

In subscriber campaigns (DM), these user variables are also available:

• {name} — full name
• {first_name}, {last_name} — parts of the name
• {username} — @username if present

Media

Click Add files to attach photos, videos, or documents. Multiple files (up to 10) are sent as a Telegram album.

• Files are listed with their base name and a hover-delete button
• Any file type Telegram accepts: JPG, PNG, MP4, MOV, ZIP, PDF, etc.
• Media is uploaded per message — no rate-limit issues beyond the standard sending delay

Forward from Saved Messages

Instead of writing text, you can forward an existing saved message (or an entire album):

Preview and Test send

At the bottom of the editor:

• Preview — shows the message as it will look in Telegram (with substitution of date/time variables)
• Test send — sends the message once to the first selected recipient. Use this before launching a long campaign.

Content rotation v4.0

Define multiple text and media variants. Each recipient gets a different one — dramatically reducing spam-pattern detection.

Enabling rotation

Pairing rule

Rotation modes

Per-variant media

Each variant has its own media list. Click Add files under any variant to attach media specific to that variant. If a variant has no media, it's sent as a text-only message.

Using rotation inside chains

Rotation works inside chains too — each step can have its own Use rotation toggle. Step 1 might send 3 text variants randomly, Step 2 might have no rotation, Step 3 might cycle through 5 different images. Each step's counter is independent.

Message chains v4.0

Turn a single ad into a multi-step dialogue — 2 to 5 messages sent one after another with configurable pauses.

Enabling chains

Each step has

• Text — separate message body
• Media — separate attachments (photos, videos, docs)
• Optional rotation — per-step toggle to define multiple variants within the step
• Delay after — how many seconds to wait before sending the next step (only shows between steps, not after the last one)

Managing steps

• Add step — append a new empty step at the end
• ↑ / ↓ arrows — reorder steps (disabled on first/last)
• X — delete a step (minimum one step must remain)

Per-step rotation

Inside any step, enable Use rotation to define multiple text+media variants for that step. The rotation mode (random/cycle) is separate per step.

Timeline preview

Click Preview to see the whole chain as a numbered timeline with per-step content bubbles and pause indicators between them.

Real-world example — Warm-up sequence

For subscriber campaigns, a 3-step chain works like this:

Schedule

Control when and how often the ad fires. Two scheduling modes, plus time windows, days-of-week and auto-stop protection.

Schedule modes

Interval mode

Set the interval in minutes. Minimum recommendation: 180 for channels, 60 absolute floor. Below that Telegram starts responding with FloodWait.

Fixed-times mode

Add one or more times of day (HH:MM). The app calculates the next scheduled run — if a day has all its times in the past, the next day's first time is used.

Time window

Restrict sending to specific hours — e.g. only during business hours. Overnight windows work too (22:00 → 06:00).

Days of week

Seven checkboxes: Monday through Sunday. Only the checked days are allowed to send. If the app is running but the current day is unchecked, it logs "wrong day" and waits.

Delays between messages

A random range in seconds. For each recipient, the delay is drawn uniformly between min and max.

Auto-stop protection

What happens when auto-stop fires

1. The campaign stops immediately
2. A log entry appears: "Auto-stop: 5 consecutive errors. Ad 'X' stopped."
3. If Telegram notifications are enabled, you receive a report in Saved Messages
4. The ad stays in your list — fix the issue and restart

Forum topics

If a selected group is a Telegram forum (with topics), you can send to specific topics — or to the main chat.

Configuring topics

What happens on send

For each recipient group that's a forum, the app sends a separate message to each checked topic. If you check 3 topics in a group and the same group is also selected for another ad, the topics apply only to this ad.

Counting recipients

The "total recipients" count in the ad details includes topic splits. A single group with 3 topics selected counts as 3 recipients.

Main chat

Always available. If you check only the main chat — no topics — the message goes to the general feed only.

Subscriber campaigns (DM)

Collect participants from any group or channel, then send them personalized direct messages.

How it works

1. You specify a source — a group or channel you have access to
2. The app fetches the participant list (with filters)
3. It sends each participant a personalized DM
4. Progress is tracked — the same user never receives the message twice

Creating a campaign

Preview participants

Click Preview on any campaign. A window opens with the list of users that would be targeted, showing name, @username and user ID. Verify the filters work as expected before launching.

Running the campaign

Click Start. The first pass runs immediately. Live stats appear in the info panel and update every second:

• Sent — messages delivered
• Skipped — users without username, privacy-protected, deactivated, bots
• Failed — errors (usually privacy or flood)
• Tracked — total distinct users who've already received a message

Skip conditions

Users are skipped silently (counted in Skipped) when Telegram returns:

• Privacy restrictions — "user doesn't accept messages from strangers"
• Not mutual contact
• Deactivated account
• You were blocked by the user

Reset progress

Click Reset to clear the "already sent" list. Use this if you want to send the same campaign again — but only after changing the message meaningfully.

Completion reasons

Group joiner

Bulk-join groups and channels from a list of links with configurable delays.

Preparing links

Paste links in the textarea — one per line. Supported formats:

• https://t.me/joinchat/XXXXX — private invite link
• t.me/username — public group or channel
• @username — public
• +invite_hash — private invite

Delay between joins

Recommended: 10–30 seconds. Lower values lead to FloodWait errors very quickly. The default 5 seconds is aggressive — you'll want at least 15.

Running the joiner

1. Paste links or click Load from file to import a .txt
2. Set the delay
3. Click Start joining

The app processes links one by one:

• Progress bar shows current position
• Each attempt is logged in the Event Log
• Live results list appears below with ✓ / ✗ indicators
• Final toast shows: N successful, M failed

Saving your list

Your link list is automatically saved in localStorage between sessions. Click Save to file to export it as a .txt for backup.

Story campaigns

Automatically publish Telegram stories on schedule. Requires Telegram Premium on the account.

Creating a story campaign

Running the campaign

Select the campaign, click Start. The app:

• Checks that the account has Premium
• Verifies the media file exists
• Publishes the first story immediately
• Schedules subsequent stories at the specified interval

Media requirements

Auto-reply Enterprise

Automatically respond to incoming private messages based on keyword matching. Enterprise plan only.

What it does

The app watches all incoming private messages on the current account. When a message matches a rule's condition, the configured action fires.

Creating a rule

Match types

Actions

Testing a rule

Click Test on any enabled reply-rule. The app sends the reply text to your own Saved Messages — useful to see exactly how it renders with variable substitution.

How rules trigger

• Incoming message is parsed
• Rules are checked in order; the first match wins
• The cooldown check happens — the same user can't be auto-replied to more often than the cooldown
• If the action is reply and delay is set, the app waits that many seconds then sends

Statistics v4.0

Full analytics dashboard: activity by day and hour, top targets, top errors, recent events with CSV export.

Filters

KPI cards

• Sent — successful sends (green)
• Errors — hard errors (red)
• Floods — FloodWait events (yellow)
• Rate — sent / (sent + errors + floods) as a percentage
• Views — total views for tracked channel messages

Charts

Activity by day — bar chart of sent per day, with an error line overlay.

Activity by hour — bar chart of sent per hour of day. Useful to spot your best sending windows.

Top targets

Top-10 most-used recipients with sent count, error count, and — for channels — total views badge.

Top errors

Top-10 error types by frequency. Useful to understand systematic issues:

• not_found — the recipient no longer exists
• privacy — user privacy restriction
• peer_flood — hard stop signal from Telegram
• flood_wait — rate-limit hit
• And others, depending on the specific error returned

Recent events

The last 30 events with timestamp, campaign name, target, and status pill. Filtered by the same period/account/campaign as the KPIs.

Channel views tracking

For broadcast channels where your account is admin, the app fetches view counts automatically in the background. Refreshed every 10 minutes for messages up to 7 days old.

Export CSV

Click Export CSV to save all events matching the current filters to a CSV file (up to 100,000 rows). Columns:

timestamp;account_id;campaign_name;campaign_type;target_name;target_kind;status;error_kind;views

Retention

Statistics are stored locally in SQLite. Events older than 90 days are automatically purged by a daily background job. Change retention in the config if needed.

Event log

Every action the app takes is logged here. Use it to monitor campaigns and diagnose problems.

Event types

• INFO (blue) — routine events: mailing started, message sent, campaign completed
• WARNING (orange) — potential issues: small interval, slow network, skipped users
• ERROR (red) — actual failures: entity not found, no permission, PEER_FLOOD

Filters

Counters

Above the log body you see live counters:

• Total — all visible events
• Sent — successful sends
• Warnings — warnings
• Errors — errors

Exporting

• Export TXT — plain text, one event per line
• Export CSV — structured with timestamp, level, kind, silent flag, account, message. UTF-8 BOM for Excel.

Copy all

Copies all filtered events to the clipboard in the same TXT format. Useful for pasting into a support ticket.

Clearing

Click Clear to wipe the visible buffer and the in-memory list. The file log on disk (data/logs/app.log) is unaffected.

Settings

All global configuration in one page.

General

Global proxy

A single proxy used by all accounts that don't have their own. Fields: type (SOCKS5 / SOCKS4 / HTTP), host, port, optional username and password.

• Save — writes to config
• Test — checks your external IP through this proxy via api.ipify.org. Result appears as a toast.
• Clear — resets all fields and removes the global proxy

Global time window

A single sending window applied to every ad and campaign across the account. When enabled it overrides per-ad settings.

Auto-start

• Auto-start all ads after authorization — when an account authorizes, every ad it owns starts immediately

Session health check

Covered in detail in the Session Health Check section:

• Enable on startup
• Auto-check interval (minutes, 0 = disabled)
• Auto re-authorize dead sessions

Telegram notifications

See the dedicated section below.

License

Shows the current plan, days left, end date. Button to re-open the activation dialog.

Data & logs

• Storage stats — total data size, accounts, recipients, campaigns counters
• Open logs folder — opens data/logs/ in your file manager
• Backup export — full profile to ZIP
• Backup import — restore from ZIP with a preview dialog
• Check for updates — manual update check
• Debug — shows a JSON dump of the update subsystem state (useful for support)

Danger zone

• Reset settings — wipes proxy, time window, autostart, session check and notification settings back to defaults
• Clear accounts — deletes every account and its session. Confirmation dialog first.

Telegram notifications

Get campaign reports right in Telegram — to your Saved Messages or any chat.

Enabling

Testing

Click Send test notification. It uses the first authorized account and sends a test message to your chosen target. If no authorized account exists, you'll get a clear error.

Events delivered

Every notification carries a formatted summary. A typical campaign-completion report looks like:

✅ Mailing completed

📣 Campaign: Promo
📤 Sent: 45
❌ Errors: 2

⏱ Duration: 12 min
🕐 14:30 — 14:42

Full profile backup v4.0

One click to export everything: config, database, sessions, ads, campaigns and statistics as a single ZIP file.

What's included

• config.json — all settings, license key cache
• autoposter.db — accounts, recipients, ads, stories, subscribers, templates, auto-reply rules, statistics
• sessions/*.session — Telegram session files (optional, see below)
• templates/ — any template folder data

What's excluded

• logs/ — log files
• exports/ — exported CSV files
• backups/ — old backups
• WAL/SHM SQLite temporary files

Exporting

Importing

Updates

The app checks for new versions on startup and offers a changelog window when one is available.

Automatic check

2.5 seconds after startup, a small request goes to the update server. If a newer version exists, a changelog dialog appears with categorized items (features, fixes, improvements, security).

Update dialog

• Download — opens the download page in your browser
• Remind later — dialog closes, will show again next launch
• Skip this version — never show this specific version again (if a newer one comes out, the dialog returns)

Manual check

Two ways:

• The download icon in the topbar
• Settings → Data & logs → Check for updates

Debug info

Settings → Debug shows a JSON dump with your current version, the server's response, and whether the update would trigger. Useful when opening a support ticket.

Data & folders

Everything is stored in one folder. Understand it, and you understand the app.

Folder locations

What's inside

Automatic backups

Every time you save settings or a campaign, the previous config.json is copied to backups/ with a timestamp. Only the 5 most recent are kept.

Restoring a config backup manually

1. Close the app
2. Open data/backups/ and find the copy you want
3. Rename it to config.json and replace the current one
4. Restart the app

Migrating to a new computer

1. Copy the entire data/ folder (or macOS equivalent) to a USB stick
2. Install the app on the new computer
3. Close it once (so it creates the empty data/ folder)
4. Replace the new data/ folder with the one from the stick
5. Launch — everything is preserved

Troubleshooting

Quick answers to the most common issues.