================================================================
Ads Pilot — OPERATOR GUIDE
================================================================

Ads Pilot sends your marketing message to a contact list over WhatsApp, Telegram, and/or Zalo — no terminal, no dashboards. You talk to it in plain English inside the Control UI chat, and it handles logins, pacing, and delivery tracking.


----------------------------------------------------------------
 HOW IT WORKS
----------------------------------------------------------------

You pick which apps to use, scan a QR code (or confirm your Telegram number) to link a marketing account, drop in a spreadsheet of phone numbers, and paste the message. Ads Pilot checks who's reachable on each app and sends — slowly, on purpose — in the background. You can pause anytime.

Everything happens by typing to the agent in chat. There is no separate app to install and nothing to run yourself on a computer.


----------------------------------------------------------------
 THE NINE STEPS
----------------------------------------------------------------

1. Name your campaign.
Give it a label, e.g. "Start a new campaign called 20% Off." One campaign can run on all three apps at once, sharing the same contact list and message.

2. Link your accounts.
For each app you want to use, say "Configure WhatsApp" / "Configure Telegram" / "Configure Zalo." You'll scan a QR code (Telegram may ask for your phone number and a login code first). Say "Skip Telegram" for any app you're not using. You need at least one linked to continue.

3. Upload your contact list.
Drop one CSV with a phone column in international format (e.g. +639171234567). Up to 5,000 unique valid numbers per upload — bigger lists get split across uploads or campaigns.

4. Paste your message.
Send the marketing text once, in chat. Don't include a greeting — Ads Pilot adds "Hi <name>," automatically when it knows a contact's name, or rotates a neutral opener when it doesn't. Zalo caps messages at 2,000 characters.

5. Optional: practice run.
Say "Start dry cron" to check who's reachable on each app without sending anything. Useful for big lists or when using more than one app. Runs in the background; no messages sent.

6. Go live.
Say "Start live" to send for real on every linked app, or target one with "Start live WhatsApp." A dry run first is optional, not required. Chat replies instantly; sends run in the background.

7. Pause anytime.
Say "Pause" to stop every scheduled check and send across all apps immediately.

8. Check results.
Say "Export results" for a downloadable spreadsheet — one row per phone number per app, with delivery status.

9. Reuse or retire.
Start a fresh campaign anytime with a new name. You can't start a new one while live sends are still running on the current one — say "Switch campaign to …" instead, or "Force new campaign" to abandon it.


----------------------------------------------------------------
 WHAT TO SAY
----------------------------------------------------------------

"Start a new campaign called …"
Creates a campaign under that name (blocked if a live send is still running on the current one).

"Switch campaign to …"
Moves to an existing campaign. Never blocked, even mid-live.

"Force new campaign"
Creates a new one anyway, abandoning any pending live work.

"Configure WhatsApp / Telegram / Zalo"
Starts login for that app and marks it ready once connected.

"Skip WhatsApp" / "Don't use Zalo"
Leaves that app out, or un-readies it if it was already connected.

"Here is my contact list" + CSV
Validates and stores the phone numbers.

"Here is the marketing message: …"
Saves the message text and asks you to confirm it.

"Start dry cron"
Practice run; checks reachability only, sends nothing.

"Start live" / "Start live Telegram"
Begins real sending, on every ready app or just the one named.

"Pause" / "Stop the schedule"
Halts every scheduled check and send.

"Export results"
Produces the results spreadsheet.

"What campaign are we on?"
Shows the current campaign name and which apps are ready.


----------------------------------------------------------------
 BEFORE YOU GO LIVE
----------------------------------------------------------------

Use dedicated marketing accounts — not your personal daily WhatsApp, Telegram, or Zalo. Keep each linked account off Zalo Web, WhatsApp Web, or any second client while a campaign is active; two active sessions on one account risks a lockout.

This is unofficial, cold outreach — account risk is real. WhatsApp, Telegram, and Zalo can restrict or ban accounts used for unsolicited messaging. Caps and slow pacing reduce that risk; they don't eliminate it. Zalo carries the highest risk of the three. There is no reliable "ban percentage" — anyone who quotes you one is guessing.

Numbers must be in international format with a + and country code — e.g. +84899681090, not 0899681090. The agent flags bad rows instead of guessing.


----------------------------------------------------------------
 CONFIGURABLE OPTIONS
----------------------------------------------------------------

Most of this is set automatically or by asking the agent in chat — you rarely need to touch a config file. It's documented here so you know what's adjustable and what each setting trades off.

>>> Sending pace

Set by saying, e.g., "arm WhatsApp with warmup pace" — or let the agent default to warmup.

Warmup (A): 4/hr, 12/day.
Default and recommended for the first several days on any new account.

Normal (B): 6/hr, 20/day.
For accounts with an established clean sending history.

Aggressive (C): about 1 per minute, 60/hr.
Materially higher ban risk. Only arms when you explicitly ask for it by name, and requires you to set an active-hours window first.

>>> Per-platform send limits

Hourly / daily cap (hourlyCap / dailyCap) — default WA 4/12, TG 4/12, ZA 3/10.
Hard ceiling on real sends per app, per hour and per day. A cron tick that would exceed it waits for the next window instead.

Send delay range (minDelayMs / maxDelayMs) — default WA/TG 60–180s, ZA 90–240s.
Random pause between two sends on the same app, weighted toward the shorter end with occasional longer gaps — deliberately uneven, not a metronome.

Registration-check delay (checkMinDelayMs / checkMaxDelayMs) — default WA/ZA 5–20s, TG 8–20s.
Pause between "is this number reachable" lookups — separate from and usually faster than the send delay.

Check caps (checkHourlyCap / checkDailyCap) — default WA 12/40, TG 8/24, ZA 8/30.
Limits lookups, not just sends — Telegram in particular restricts accounts that resolve too many phone numbers too fast.

>>> Active hours

Send window (schedule.activeHoursLocal) — default off (24h).
Restricts sending to a start–end hour range. Off by default. Set it by telling the agent your intended window in your own timezone — it converts to the server clock for you. Required before arming the aggressive pace.

>>> Contact list

Max list size (maxContactsPerUpload) — default 5,000.
Unique valid phone numbers accepted per upload. Larger files are rejected outright — split the CSV or start a second campaign rather than re-uploading the same file.

Soft-warn threshold (contactsSoftWarn) — default 1,000.
Above this the agent flags the list size as worth a dry run first but still accepts it.

List quality gate — default blocks above 50% skip or 30% duplicate ratio.
A list with too many unreachable or duplicate numbers is refused at arm/send time rather than burning send attempts on bad data.

>>> Message

Character limit (Zalo only) — 2,000 chars.
Applies whenever Zalo is one of the enabled platforms for the campaign.

Message variants (templates/message.txt) — optional.
Separate two or more versions of your pitch with a line containing only "---"; each successful send rotates to the next variant.

Greeting personalization — always on.
"Hi <name>," when the app surfaced a real contact name, otherwise a rotating "Hi there / Hello / Hey." Not yet configurable per campaign — don't write your own greeting into the message.

>>> Automatic stop conditions

Consecutive failures (maxConsecutiveFailures) — default 3.
That many failed sends in a row pauses the platform for you to investigate.

Telegram flood signals (flood_wait / peer_flood) — hard stop.
Telegram's own anti-spam responses immediately disarm Telegram sending — this isn't a tunable knob, it's Telegram telling you to stop.

Cooldown after a hard stop (coolDownMs) — default 60 minutes.
Minimum wait before that platform can be re-armed — resist the urge to immediately push volume to "catch up."