Skip to content

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:

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

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_settings row whatsapp_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.

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.

  • Another blast is running and 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.

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.

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 (con2026Outreach router, admin only).
  • The follow-up never asks which card someone would bring, because signing eligibility varies by artist and package.

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, retaining utm_source=wa_auto, utm_medium=whatsapp, utm_campaign=con2026_outreach and adding utm_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.

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.

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. approverPhone must 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 groupMessageId and action within 7 days returns 409 duplicate_command, and nothing is sent again.
  • Uncertain outcomes. A 202 unknown or a 502 send_failed means: 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.

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