whatsapp_agent_automation v1.0.0

name: "whatsapp_agent_automation" description: "Run business messaging on WhatsApp for an agent: send via Meta's Cloud API, manage approved message templates, track the 24h customer service window, keep an opt-in ledger, and run compliant campaigns. Triggers when the user needs WhatsApp business messaging, templates, opt-in/opt-out handling, or campaign deliverability." metadata: { "includeInPrompt": true }

WhatsApp Agent Automation

Purpose

Operate WhatsApp Business Platform messaging from an agent without a BSP middleman: direct Cloud API sends, pre-approved templates, a per-contact opt-in ledger, automatic 24-hour window tracking, and throttled campaign sends that keep the number's quality rating green. Covers setup through campaign ops and deliverability.

Workflow

1. Decide the route. Meta's Cloud API (self-serve, free platform, you build the UI) vs a BSP (Wati, Interakt, AiSensy: managed inbox + builders, platform fees). Agents that automate usually take direct Cloud API: a Meta app of type Business with the WhatsApp product, then a Phone Number ID and access token from WhatsApp > API Setup. Production uses a permanent System User token, never the temp setup token. A number already on the WhatsApp mobile app must be permanently deleted there before migrating to the API.
2. Wire the webhook. Callback URL + your own verify token in WhatsApp > Configuration, subscribe to the messages field. GET answers the hub.challenge handshake; POST checks X-Hub-Signature-256 HMAC against the app secret, acks 200 immediately, then processes. Parse inbound messages and status updates (sent -> delivered -> read / failed) from the payload; dedupe by message id. See references/webhooks.md.
3. Register opt-ins before any outbound. There is no consent field in the API: Meta enforces consent after the fact through quality rating and bans. Record every contact's opt-in with wapp optin: exact consent wording, timestamp, source channel, message-type permission. Never import a cold list; re-permission old lists with one confirmation request and keep only the yes replies. Wire inbound webhooks to wapp inbound so STOP/UNSUBSCRIBE/CANCEL keywords auto-withdraw consent.
4. Get templates approved. Every business-initiated message outside the 24h window must be a pre-approved template, categorized Marketing / Utility / Authentication. Submit from WhatsApp Manager; review runs minutes to a day or two. Rules in references/templates.md. Until approval, the flow cannot start cold.
5. Send with window awareness. A user message opens a 24-hour customer service window: free-form replies allowed, each new user message resets it. Check wapp can-send --wa-id before choosing free-form vs template. For campaigns, use wapp campaign with a CSV of opted-in contacts; it skips non-opted-in rows and throttles to the rate you set. Keep interactive buttons in templates: quick-reply buttons reopen the free window faster than waiting on free text.
6. Watch quality and cost. The number carries a green/yellow/red quality rating from block and report rates; low ratings cut the messaging ladder (250 -> 2,000 -> 10,000 -> 100,000 -> unlimited unique recipients per 24h, per business portfolio since Oct 2025). Billing is per delivered template message by category and country since July 1, 2025; service replies have 1,000 free per number per month, then bill at utility rate from Oct 1, 2026. Details in references/billing.md.

Output Contract

• A send is either delivered via POST https://graph.facebook.com/{api-version}/{phone-number-id}/messages with a returned wamid, or a dry-run payload the caller can inspect.
• Every outbound contact has an opt-in record (source + timestamp + consent copy) in the ledger; opt-outs stay on the record as proof of stopping.
• Every campaign logs rows sent, rows skipped (with reason), template name, and timestamp.
• No contact is ever messaged without a valid opt-in, and no free-form text goes out when the 24h window is closed.

Operating Rules

1. Consent first, always. If a contact has no opt-in record, do not send: build the opt-in, then the message.
2. Template-only outside the window. Free-form only when can-send says the window is open.
3. One topic and one CTA per template; never hide promotional copy in template variables; classify marketing as marketing.
4. Honor opt-outs on the same interaction they arrive: keyword match, withdraw consent, confirm back, stop all templates to that contact.
5. Keep sends spaced: stay far under the 80 msg/sec per-number ceiling; per-campaign throttling defaults to 2/sec.
6. Live sends require WAPP_TOKEN and WAPP_PHONE_NUMBER_ID env vars and explicit --live; credentials never go in files or the ledger.
7. Meta's policies and rates change: verify pricing and policy against Meta's WhatsApp docs before committing to a high-volume plan.