How PromotionBot works
The mental model — organisations, numbers, groups, tags, the queue, campaigns, events, and the gates every send passes through.
Nine concepts explain the whole product. Once these click, every page in the app is obvious.
Your organisation#
Everything you create — numbers, groups, tags, campaigns, analytics — belongs to your organisation. One person owns it, and everyone you invite joins it. Data never crosses between organisations.
The person who signs up is the owner. See Team, roles & approvals for what each role can do.
Numbers (sessions)#
A number is a WhatsApp account you've linked by scanning a QR code. Internally each one is a session, which is why you'll occasionally see that word.
Most organisations run one shared number that the whole team sends through. Larger plans allow several — a main association number plus one per committee, say. Groups, sends, and analytics are all scoped to the number they belong to, so two committees on two numbers never see each other's traffic.
Detail: Numbers.
Groups#
A group is a WhatsApp group chat the linked account is a member of. PromotionBot imports the list; it cannot create groups, join groups, or add members. If you want to reach a group, put the linked account in it the normal way, from WhatsApp.
Tags (categories)#
A tag is a label on a group — first-year, alumni, committees. You tag once and then target the tag,
which is the difference between a two-second send and picking 40 checkboxes.
A group carries exactly one tag at a time. Untagged groups sit in the general bucket.
Presets are named bundles of tags, so everyone can mean "all six year groups plus alumni" without you
selecting them each time.
Detail: Groups, tags & caps.
The queue#
Nothing sends instantly except an explicit "send now". Everything else — a scheduled message, an event timeline, a recurring campaign — becomes a row in the queue with a time attached.
A scheduler wakes up every minute, looks for queue rows that are due, and dispatches them. This is why the app keeps working when your laptop is closed, and why a scheduled send fires reliably at 18:00 in your organisation's timezone rather than the server's.
Campaigns#
A campaign is a repeating send with a name — a weekly digest, a monthly alumni update. It keeps firing on its schedule until you pause or archive it, and its sends are attributed to it in analytics so you can see whether the campaign as a whole is working.
Detail: Campaigns & calendar.
Events#
An event is a thing with a date. You describe it once — name, date, audience — and PromotionBot generates a whole promo timeline of queued messages leading up to it, each with a role: save-the-date, announcement, reminder, last call, day-of. Edit the copy, drop the slots you don't want, launch.
Detail: Events.
Approvals#
If your team shares one number, you probably don't want everyone broadcasting to the whole association unreviewed. Non-admins sending on the shared number create a pending request instead of a send; an admin approves or rejects it. Nothing reaches WhatsApp until someone with authority says yes.
Detail: Team, roles & approvals.
The gates every send passes#
This is the part worth internalising. Between "I clicked send" and "WhatsApp received it", each targeted group is checked against four gates. A group that fails one is skipped — the rest of the send continues.
| Gate | What it does | Where you control it |
|---|---|---|
| Inactive | Groups marked inactive are never messaged. | Groups |
| Daily / weekly cap | A group can't receive more than N messages per day (and optionally per week). | Groups |
| Cooldown | The same campaign, event, or recurring send can't hit the same group twice inside 20 hours. | Not adjustable org-wide; can be turned off for one group in Groups |
| Quiet hours | If the number is inside its quiet window, the send is held until the window ends rather than skipped. | Numbers |
How long the cooldown actually is#
20 hours, for every scheduled source:
| What's sending | Cooldown |
|---|---|
| A campaign or recurring send, at any repeat interval | 20 hours |
| A one-off scheduled send from Compose, or an event timeline slot | 20 hours |
| Firing a campaign manually ("fire now") | 20 hours |
| An ad-hoc send from Compose | none — no cooldown at all |
It is 20 rather than 24 for one reason: a daily campaign re-fires roughly 24 hours after its last send, so a longer window would block the campaign with its own previous send and it would never run twice. 20 hours leaves it room while still stopping a genuine double-send.
The cooldown window is 20 hours for everything.
Two more details people get wrong:
- Cooldown is per source, not per group. Two different campaigns can both message the same group on the same day — the cooldown only stops one campaign from repeating itself. The daily cap is what limits total volume into a group.
- Ad-hoc sends have no source, so no cooldown applies to them at all. Only the daily cap does. Manually firing the same message twice from Compose will send it twice.
Then, for each group that passes, the send itself is deliberately slow: a typing indicator, a pause scaled to message length, the send, then a randomised gap before the next group — with an occasional longer pause. See Staying unbanned for the actual numbers and why they exist.
Link tracking#
Any http(s):// URL in your message is rewritten, per group, into a short tracking link before it goes out.
Group A and group B get different short links pointing at the same destination, which is how
Analytics can tell you that alumni clicked and second-years didn't.
Recipients see a promotionbot.net/r/... link — or your own domain, on the Pro plan.