WhatsApp outreach and the Sales Desk
WhatsApp goes out through apps/whatsapp-gateway: one Baileys session, an
unofficial client on a single linked phone. WhatsApp bans that kind of number
for behaving like a spammer. Everything on this page is built around one fact:
Two kinds of send
Section titled “Two kinds of send”| Cold (unsolicited) | Reply | |
|---|---|---|
| Examples | Vendor blast, convention outreach | Admin inbox reply, Sales Desk GO/EDIT/reply |
| Limit | Shared daily cold budget | Only to someone who wrote to us recently |
| Opt-out | Every blast ends with “Reply STOP to opt out.” | STOP is checked before each send |
The shared cold-send budget
Section titled “The shared cold-send budget”packages/core/src/server/whatsapp/cold-budget.ts. Every unsolicited send
draws from one daily budget, so running several features at once can never
add up to more than the number can take.
- The cap is
WHATSAPP_COLD_DAILY_CAP(default 40). It is set by env, with no admin UI. Lower it for a few days after re-linking a number. - A day is a MYT calendar day. The counter is the single
site_settingsrowwhatsapp_cold_budget({ day, count }). claimColdSend()takes one slot with a conditional upsert. A new day resets the count, and the update is refused once the count reaches the cap. Two senders cannot both take the last slot.- Vendor blasts claim a slot before every send. Convention outreach claims inside its send transaction, so a failed send rolls its claim back.
Vendor blasts
Section titled “Vendor blasts”Sent from the WhatsApp inbox (VendorBlast.tsx) to shops in a
vendor contacts
category. The procedure is vendorContacts.blast in
packages/core/src/server/trpc/routers/vendorContacts.ts, open to admin and
editor and audited as SEND_VENDOR_CONTACT_BLAST.
Refused up front
Section titled “Refused up front”- Another blast is
runningand has ticked in the last 10 minutes. (The longest gap between sends is 5 min, so a blast quiet for longer than that is dead, usually killed by a deploy.) - No sendable numbers are left after dropping numbers that opted out (STOP) and imported rows whose phone still needs fixing.
- More than 300 recipients.
- The gateway health check fails: “WhatsApp is offline”.
- The list is bigger than today’s remaining cold budget. The error says how many slots are left. Pick fewer shops, or send the rest tomorrow.
While it runs
Section titled “While it runs”The send loop runs as a detached promise in whichever process served the tRPC
call (the API, when API_INTERNAL_URL is set). The page polls the blasts list
for progress.
- The gap between sends is random between 1 and 5 minutes (about 3 min on average, so 100 contacts take about 5 h).
- Before every send, the blast stops early, without finishing its list, if any of these is true:
| Status | Trigger |
|---|---|
stopped_offline |
Gateway health check fails |
stopped_risk |
3 or more recipients replied STOP since the blast started, or more than 10% of sends failed after at least 10 attempts |
stopped_limit |
The daily cold budget ran out |
Each stop sends a Sentry warning (Vendor blast stopped) and shows on the
blast row in the inbox. Every body gets “Reply STOP to opt out.” appended,
unless it already contains STOP. A STOP reply costs nothing. A “Report” is
what gets a number banned.
Convention outreach
Section titled “Convention outreach”packages/core/src/server/whatsapp/con2026-sender.ts, driven every minute by
POST /api/cron/con2026-outreach. It sends approved convention invitations
and follow-ups. It is paced much more tightly than blasts:
- Monday to Saturday only, 10:30–13:00 and 14:30–19:30 MYT, up to the campaign cutoff of 2026-11-02 23:59 MYT.
- At least 8 minutes between sends, no more than 5 an hour, and a daily cap (default 5, at most 25). All of it also draws from the shared cold budget.
- It pauses itself (
risk_threshold) after 3 STOPs or 3 negative replies (scam, angry, under 18, wrong person, “who is this”). Only replies that arrive after an owner unpauses count toward the next pause. - Admins prepare, approve, kill and pause it from the Outreach panel on
/admin/whatsapp(con2026Outreachrouter, admin only). - The follow-up never asks which card someone would bring, because signing eligibility varies by artist and package.
B/D copy for the 2 November waves
Section titled “B/D copy for the 2 November waves”Both steps open with “Hi {first}! Kokoro from TCGKL 2026 here 🐯 (6–8 Nov,
KLCC)”, falling back to “Hi there!” when no safe first name is available.
The offer name, artists and base price (RM299, for example) come from the
current offer; the promotional body does not add fee text.
- Himeno: event promo card + one approved personal item; licensed-series items aren’t eligible. Other offers point to what each artist signs on the booking page rather than promise personal-card eligibility.
- Local Artist Collective: Sidsoot, Nic CCArt and Pid sign one promo card; Potato Art Club adds a signature + small sketch. Step 2 also says “Promo only; no personal cards.”
- “Includes one free 3-Day Pass per account.” appears only when the live offer includes entry. Otherwise, tier D / Collective copy says “No pass included; use your pass for that day.”
- Both steps include the direct booking link:
?artist=<slug>&package=<id>for packages or?bundle=<id>for bundles, retainingutm_source=wa_auto,utm_medium=whatsapp,utm_campaign=con2026_outreachand addingutm_content=<tier>_s<step>. Without an artist slug, packages fall back to the tagged event page:?package=<id>alone does not open the artist drawer. - Tier B sends a matching artist offer-sheet image with the body as its caption; unmapped offers and tier D stay text-only, and the sheet filename participates in
render_hash. - “Reply STOP to opt out.” remains the last line. Copy/link changes change the
body SHA-256
render_hash; a stale approval cannot send the new body without preparation and approval again. Pacing, caps and risk thresholds are unchanged.
The same cron also expires stale reply drafts and reconciles drafts stuck mid-send before it runs.
Reply drafts
Section titled “Reply drafts”When an outreach contact replies, classifyOutreachReply
(packages/core/src/server/assistant/match.ts) labels the reply.
draft-writer.ts may then propose a reply draft for staff to approve. A draft
expires 24 h after the inbound message.
Neither classifyOutreachReply nor the draft writer parses the outbound
greeting or invitation. Classification uses the inbound text; drafting resolves
the original structured source hints and offer_ref against live offers.
The reply writer’s existing event-link allowlist is independent of the direct
links in promotional bodies. Miccy / Sales Desk draft approval needs no wording
change.
- Wording about orders and after-sale support is checked first and is never auto-drafted. It always goes to staff as an urgent order review. That wording includes refund, receipt, payment, “my booking”, “semak tempahan”, “check booking status”, an order number, and broken-link or “tak boleh bayar” reports.
- A bare “booking link” or a price question is buying intent, and does get a draft.
- Under 18, scam, angry and asks-for-a-human replies are never drafted.
Sales Desk
Section titled “Sales Desk”The Sales Desk is the staff WhatsApp group, plus an assistant (Miccy) that
calls a token-authenticated API on the API host. The assistant can act only on
an explicit command from an active staff member in that group. The full
contract, including error codes, duplicate-command rules and the audit shape,
is in docs/whatsapp-assistant/sales-desk-api.md. Read it before you change
anything under packages/core/src/http/ops/.
| Endpoint | Does |
|---|---|
GET /api/ops/sales-desk/drafts |
Newest 50 open reply drafts, contact masked |
POST /api/ops/sales-desk/decision (or /drafts) |
GO, EDIT, SKIP or MINE on a draft |
POST /api/ops/sales-desk/reply |
Send one staff-approved free-text reply on WhatsApp or Instagram |
POST /api/ops/sales-desk/done |
Mark inbox items done |
GET /api/ops/sales-desk/ticket-update |
Entry-ticket sales snapshot |
GET /api/ops/sales-desk/sales-report?report=signing|entry |
Stakeholder sales report text |
Rules that hold across the API:
- Auth.
Authorization: Bearer $SALES_DESK_TOKEN. The token must be at least 32 characters. If it is unset, every call fails closed with a 500.approverPhonemust belong to an active assistant staff contact. - Budget. At most 60 command units per rolling hour, shared by decisions, replies and DONE.
- Idempotency. The same
groupMessageIdand action within 7 days returns 409duplicate_command, and nothing is sent again. - Uncertain outcomes. A 202
unknownor a 502send_failedmeans: check the inbox, never retry. A provider failure on an Instagram send also goes to Sentry. - Audit. Every command is audited with
via: "sales-desk". The audit row never stores the reply text or the raw approver phone.
Instagram replies go through the same sender the admin inbox uses
(packages/core/src/server/instagram/send-reply.ts). itemKey is the thread
id from the inbox’s ?ig= link. A send is refused once the customer’s latest
message is 24 h old, because Instagram’s messaging window has closed (provider
error 2534022 has the same meaning). It is also refused if an identical reply
went to the thread in the last 2 minutes. WhatsApp replies go only to a
number that wrote in within the last 30 days, never to a number that opted
out, and never over an open draft.
Sales reports. The signing or entry report comes from the same builder as
Admin → Sales Update (packages/core/src/server/reports/stakeholder-report.ts).
Treat it as internal financial data. A comp booking adds zero to sold or
collected. A report read is audited as READ_SALES and spends no budget.
Related cron
Section titled “Related cron”| Endpoint | Schedule (UTC) | Job |
|---|---|---|
/api/cron/con2026-outreach |
every minute | Draft sweeps, then one outreach send if every gate passes |
/api/cron/instagram-sync |
every 30 min | Pull Instagram DMs into the admin inbox |
