WhatsApp Business Ops

WhatsApp Business Management

WhatsApp is not a discovery channel — it is a conversion channel. The goal is not to send fast: it is one qualified hand-off per opt-in lead, no unsolicited bulk, no duplicate send. Reference BSP: Whatchimp (Meta Business Partner); any BSP works.

Access, data, and network — read before running

Every access is opt-in — each one stays off until you fill its placeholder in ## Configure. The default is no network.

Personal data persisted, in full: display name, case type, free-text situation, conversation timestamps, template-send log, alert log, per-run recaps. Phone numbers are stored raw ONLY in wa-crm-state.md (the system-of-record mirror); every duplicate register and the blacklist key on sha256(phone)[0:12]. That is lead PII on disk — ## Data minimization and retention is doctrine, not an appendix. Scope the API token to the one business number; never reuse a full-account token.

When to Use

Configure

# /config.yaml
whatsapp:
  phone_number_id: 
  base_url: https://app.whatchimp.com/api/v1   # swap host for another BSP
templates:
  first_contact: 
  followup_soft: 
  followup_hard: 
  closing: 
crm: { sheet_id: , tab: "Leads" }
alerts: { primary_chat: , channel: telegram }
retention: { lead_days: 90, recap_days: 30, template_log_days: 30 }
inbound_pipeline:
  shared_queue_file: /../shared/leads-whatsapp.json
schedule:  # dm_check "*/2 9-22 * * *" · add_contacts "*/5 9-22 * * *" · follow_up "0 10 * * *"
  timezone: Europe/Paris

The 24h window — the central law

After any message a user sends you, you have 24 h to reply in free-form. After 24 h of user silence, only Meta-approved templates, each billed as a new conversation. Free-form to a cold conversation → API rejection or a marketing-conversation bill + a quality hit; exit code 2, always skipped. Check window state before every outbound send:

curl -s "https://app.whatchimp.com/api/v1/whatsapp/get/conversation" \
  -d "apiToken=" -d "phone_number_id=" \
  -d "phone_number=" -d "limit=1"
# Output: {"status":1,"data":[{"sender":"user","created_at":"2026-07-16T09:12:04Z"}]}
# sender="user" and < 24h old  → free text OK. Otherwise → template.

Session check first on every cron:

curl -s "https://app.whatchimp.com/api/v1/whatsapp/subscriber/list" \
  -d "apiToken=" -d "phone_number_id=" \
  -d "limit=1" -d "offset=1"
# Output: {"status":1,"data":[...]}   401/403 → stop+alert · 429 → stop, wait next run

Timeout > 10 s → BSP down: one retry, then stop and alert. Never retry in a loop. A 200 OK carrying status=0 is a failure, not a send. Never send a "test" message to a real lead — use a dedicated test number. Never auto-rotate an API token from inside a cron; rotation is a human action.

Phase gating and quotas

Meta assigns each number a tier: T1 1k uniques/24h · T2 10k · T3 100k · T4 unlimited. New numbers start at T1. Tiers rise on volume + quality, and fall — or the number gets paused — when quality drops.

Read memory/wa-state.md at start of every run. Phase B is a manual flip, never automatic. Any quality drop → revert to A immediately.

Follow-up cadence: J+1 soft · J+3 soft · J+7 hard · J+15 hard · J+20 closing → status=lost. Stop after the closing template. Continuing past J+20 is ban-risk territory.

Duplicate guard — the most important section

Quality-score collapse is dominated by duplicate template sends. Three registers, read before every outbound action:

If in doubt, SKIP. It is always better to skip than to send a duplicate. This one rule is the difference between a number that stays Tier 2 for years and one paused in 30 days.

Alert only when a lead replies AND qualifies — never after a first template send. Alerting on first contact generates dozens of false alerts and trains the human team to ignore the channel.

Data minimization and retention

The registers above hold lead PII — a regulated store, not logs.

Identity — disclose, never dodge

If a lead asks whether they are talking to a bot, a human, or an AI: say so plainly, in the same message, and offer the human.

You're talking to 's automated assistant. I can take your details
now and a specialist will call you back — or I can pass you to them right away.

No ambiguity, no pivot, no "I'm part of the team". Honest disclosure is not a cost here: a lead who discovers the automation later is a complaint, a block, and a quality-score hit. Blocks and reports are exactly what Meta measures. Disclosure is account safety. Escalate to a human — stop the automated replies for that thread and alert — when the lead asks for a human, asks twice about identity, or raises anything the templates do not cover.

Reply rules (free-form, inside open window)

• Match tone. Short messages. One ask per message. Reassuring on stressful topics, never dramatizing. Reread the full visible history before composing.
• Never: definitive price quotes (soft "starting at" only if asked) · outcome guarantees · confidential client info · documents/PDFs to non-clients · anything outside the brand's scope.

Skeletons: A greeting + "how can we help" · B empathy + one contextual question · C hand-off: Thank you for these details. A specialist from will call you back. Could you confirm your name and the best time to reach you?

Classify every thread before drafting — case type is what the alert payload and the recap carry. Structure below, questions are yours:

"Too many questions" failsafe — after 5 questions with no contact info, switch: "To answer precisely, a specialist needs to call you back. Could you confirm your name + best time?" This converts more question-only threads than any other tactic.

Qualification requires: thread open · not blacklisted · not already "qualified — awaiting callback" · no auto-reply in the last 60 s (anti-cascade). Any check fails → skip.

Flow

wa-inbound (every 2 min)

1. Session check. 2. subscriber/list unseen_count>0 — if 0 unread → STOP.
3. Per unread (≤20 A / ≤50 B): get/conversation limit=20 → if last sender="bot" SKIP
   → qualify → draft → normalize encoding → POST /whatsapp/send → verify status=1.
4. If qualified: check wa-alerts-sent.md → if absent, alert primary chat, append hash.
   UPDATE the CRM row (wa-inbound never APPENDs). 5. Recap.

wa-outbound (every 5 min)

1. Session check. 2. Read shared queue, filter status="pending" — if 0 → STOP.
3. Per lead: template-log 24h check → subscriber/create → POST /whatsapp/send/template
   template_id= → verify status=1 → queue status="first_message_sent"
   → APPEND CRM row (only cron that appends) → append template log.
4. Never alert from this cron. 5. Recap.

wa-followup (daily 10:00)

1. Session check. 2. CRM: status in {first_message_sent, follow_up_sent}, idle at a J+N mark.
3. Per candidate: template-log check → send cadence template → update CRM + log. 4. Recap.

WhatsApp Web via Playwright — gray area, not recommended

Running Playwright against web.whatsapp.com is outside WhatsApp's Business Terms and risks a permanent number ban. It is documented here only as a read-only contingency while BSP approval is pending, and it is not recommended for production. Requires an explicit human decision per incident — an agent must not choose this path on its own. Sessions rotate the QR link unpredictably (daily manual re-login); no template sends are possible; quality score still applies at the number level. If a login challenge or automation check appears: stop and hand the session to a human. Never tune timing to avoid a detection check. Migrate back to the BSP API as soon as approval lands.

Exit codes

Output Format — mandatory recap

Every run ends with this, verbatim, to the alert channel and appended to memory/wa-recaps.md:

[Job name] — [status: ok|partial|blocked|skipped]
Inbound replies: [N or "—"]
Templates sent: [N or "—"]
Qualified leads: [count + first names only]
Phase / Tier: [A|B / Tier 1|2|3|4]
Quality score: [green|yellow|red]
Blockers: [text OR "—"]
Next action: [1 line]

Filled instance:

wa-inbound 10:32 — status: ok
Inbound replies: 7
Templates sent: —
Qualified leads: 2 (Marc, Lina)
Phase / Tier: A / Tier 1
Quality score: green
Blockers: —
Next action: human callbacks due before 12:00

Better silence than spam. Better a blockage report than a fake success. Never fake a successful send.

Troubleshooting

Memory files

memory/: wa-state.md (phase/tier/quality) · wa-alerts-sent.md · wa-template-log.md · wa-crm-state.md · wa-blacklist.md (hashes) · wa-clients-known.md · wa-recaps.md · wa-learnings.md · wa-incidents.md. Shared: ../shared/leads-whatsapp.json (written by upstream social agents, read by wa-outbound).

mkdir -p "/memory" && chmod 700 "$_" && cd "$_" && for f in wa-recaps wa-state \
  wa-alerts-sent wa-template-log wa-crm-state wa-blacklist wa-clients-known wa-learnings \
  wa-incidents; do [ -f "$f.md" ] || : > "$f.md"; done
mkdir -p "/../shared" && Q="/../shared/leads-whatsapp.json"
[ -f "$Q" ] || echo '[]' > "$Q"   # wa-outbound reads this at step 2 — absent = first run crash
# Output: (silent, idempotent) — existing files are never truncated

First-run checklist

• Placeholders filled; token scoped to one number.
• BSP account approved, business number verified by Meta, ≥3 templates approved.
• memory/ exists, chmod 700, retention values set in config.yaml.
• Alert channel tested with "hello" — and confirmed as an acceptable destination for lead names.
• Opt-in pipeline documented: how each lead consented, and where that proof lives.
• Phase A confirmed, quality green.
• Human team review: who reads alerts, callback SLA, escalation path, who handles deletion requests.

Scope

This skill ONLY: operates a WhatsApp Business number through a BSP API you own · sends free-form inside an open 24h window and Meta-approved templates outside it · contacts leads who opted in on another channel · qualifies and hands off to a human · keeps a masked, retention-bounded local state to avoid duplicates.

This skill NEVER: sends unsolicited bulk or non-opted-in outbound · sends free-form to a cold conversation · hides or denies the automation when a lead asks · adapts timing or behavior to slip past an automated check — when one appears, it stops and a human takes over · stores case documents or special-category data in memory files · retains lead data past the configured window · creates a second number to work around a Meta pause · rotates tokens or restarts infrastructure by itself.

Meta's WhatsApp Business Terms, the WhatsApp Business Messaging Policy, and your jurisdiction's privacy law are binding constraints on every run in this document. Where this doctrine and those rules disagree, those rules win.