WhatsApp Integration Hub
WhatsApp (Meta Business Platform, routed via Twilio BSP) is OpenClaw’s planned international messaging channel for buyer/seller outreach in markets where domestic SMS is unreliable or blocked. Currently staging — no production traffic flows through WhatsApp today. The integration is deferred pending 10DLC resolution on the domestic SMS tier and sufficient international deal volume to justify BSP onboarding costs and template approval overhead. All messaging compliance gates from the domestic SMS cluster apply here with stricter opt-in requirements imposed by Meta.
Quick Reference
| Property | Value |
|---|---|
| Vendor | Meta Platforms (WhatsApp Business Platform) |
| URL | business.whatsapp.com |
| KB doc | /home/opsadmin/.openclaw/workspace/knowledge-base/whatsapp/API.md (via Twilio BSP, last_verified: 2026-03-04) |
| Auth method | HTTP Basic Auth — Twilio Account SID + Auth Token (BSP path); Bearer token (Cloud API direct path) |
| Auth credential (Twilio BSP) | op://Aurora/twilio/account_sid + op://Aurora/twilio/auth_token |
| Auth credential (Cloud API) | op://Aurora/whatsapp/api_token (pending provisioning) |
| Cred-proxy port | n/a (until B1-B6 from NemoClaw audit ratified) |
| Webhook port | n/a (not yet wired) |
| Webhook handler | n/a — planned: workspace/webhooks/whatsapp-handler.js |
| Webhook dedup table | processed_webhook_events (24h TTL) |
| Tunnel path | /webhook/whatsapp (planned — must be registered in FUNNEL-REGISTRY.md before any public exposure) |
| Outbound API base (Twilio BSP) | https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/ |
| Outbound API base (Cloud API) | https://graph.facebook.com/v21.0/ |
| Sandbox number | whatsapp:+14155238886 (Twilio Sandbox — dev/testing only) |
| Number format | whatsapp:+1XXXXXXXXXX (E.164 with whatsapp: prefix) |
| Rate limits | 80 msg/sec default (Twilio BSP); 1,000 msg/sec Cloud API direct; Meta Tier 1 = 1,000 unique users/day |
| Rate-limit action | 429 → exponential backoff (3 retries, 1s/2s/4s), Discord ops alert |
| Cost (Twilio BSP) | ~0.085/message (by country); ~$1.15/mo per WhatsApp-enabled number |
| Cost (Cloud API) | ~0.07/conversation window (24h); varies by country and category (UTILITY / MARKETING / AUTHENTICATION) |
| Pricing change | Meta updated rates effective April 1, 2026 — verify current rates at twilio.com/pricing before any campaign |
| Backup/recovery | Vendor-owned (Meta/Twilio SLA) |
| Discord alert channel | ops |
| Drift cadence | on-API-change |
| Status | staging |
Components
No production webhook handlers or scripts exist yet. The following are planned or referenced:
| Component | Path | Status | Notes |
|---|---|---|---|
| Webhook handler | workspace/webhooks/whatsapp-handler.js | Planned | Not yet created |
| Outbound script | workspace/scripts/whatsapp-send.js | Planned | Not yet created |
| Twilio SDK (Node) | npm install twilio | Available | Used by twilio-voice-handler (:18797) already installed |
| KB doc | knowledge-base/whatsapp/API.md | Present | Twilio BSP path documented, last_verified 2026-03-04 |
| Audit (2026-05-02) | knowledge-base/whatsapp/_audit/2026-05-02.md | Present | 53 findings — deprecation warnings + feature gaps |
| Audit (2026-05-04) | knowledge-base/whatsapp/_audit/2026-05-04.md | Present | 0 findings |
Key audit finding (2026-05-02): On-Premises WhatsApp Business API is EOL (closed May 15, 2024; shelved October 23, 2025). Any future implementation MUST use Cloud API or a BSP fronting Cloud API. Current KB documents the Twilio BSP path — valid approach.
How It’s Used
- Trigger: International contact (CH seller or buyer) has a non-US number, or domestic SMS delivery fails after retry exhaustion across Twilio (:18797) and SalesMsg (:18793). Aurora or the acquisitions-outreach skill determines WhatsApp as the fallback channel.
- Workflow: Aurora constructs a pre-approved Meta template message → outbound via Twilio BSP (
POST /Messages.jsonwithwhatsapp:+E164prefix onTo/From) → delivery status tracked viaStatusCallbackwebhook → status written to Supabasetool_callsrow (CHOKEPOINT-1) → HubSpot contact timeline updated. - Agents involved: _summary (outbound brain, channel selector), _summary (acquisition stage gating, channel escalation decision).
- Failure mode: Template not approved by Meta (error 63003) or recipient not opted in (63001). Both are permanent failures — do not retry. Log to
tool_callswithresult_ok: false, alert Discord ops, flag contact for manual outreach. - Success:
MessageStatusprogressesqueued → sending → sent → delivered → read.delivered= success threshold.read= engagement signal. Both written back to Supabase and HubSpot timeline.
Message Architecture (Twilio BSP Path)
Aurora / acq-outreach skill
↓
POST api.twilio.com/Messages.json
From: whatsapp:+14155238886
To: whatsapp:+[E164]
ContentSid: HX... (approved template)
ContentVariables: {"1": name, "2": address, ...}
↓
Meta WhatsApp Servers
↓
Recipient's WhatsApp app
↓
StatusCallback → /webhook/whatsapp/status (planned, :TBD)
↓
processed_webhook_events dedup (24h TTL)
↓
Supabase tool_calls + HubSpot timeline
24-hour window rule: After a contact messages OpenClaw first, freeform replies are allowed for 24h. Outside that window, only approved templates are permitted. Track last_inbound_at per contact in Supabase to enforce window gating.
Template Requirements
All business-initiated messages require Meta-approved templates. Templates are created via Twilio Content API and submitted to Meta for approval (typically 24–72h).
| Template Category | Use Case | Approval Speed |
|---|---|---|
| UTILITY | Appointment reminders, status updates, confirmations | Fastest (~24h) |
| MARKETING | Deal alerts, dispo broadcasts, property announcements | Medium (~48h) |
| AUTHENTICATION | OTP, verification codes | Fastest |
Template variables use {{1}}, {{2}} notation. Always pre-test in Twilio Sandbox before submitting for approval.
2026 AI policy constraint (effective Jan 15, 2026): WhatsApp Business Solution Terms prohibit using WhatsApp as the primary delivery surface for a general-purpose AI assistant. Aurora’s WhatsApp integration must be structured as task-specific workflows (lead qualification, appointment scheduling, status updates) — not an open-ended chatbot.
Opt-in and Compliance Requirements
Meta requires explicit written opt-in before sending any message to a contact. This is stricter than domestic SMS A2P 10DLC requirements.
Opt-in collection methods:
- Web form with WhatsApp checkbox
- Click-to-WhatsApp ads (Meta Ads Manager)
- QR codes at open houses or direct mail
- Inbound message from user (implicit opt-in for 24h window)
Opt-out handling: STOP / UNSUBSCRIBE replies must be handled in the webhook handler. Remove from WhatsApp list immediately. Failure to honor opt-outs risks WhatsApp quality score degradation and number ban.
Quality rating tiers (Meta messaging tiers):
| Tier | Daily Limit | Upgrade Requirement |
|---|---|---|
| Tier 1 | 1,000 unique users/day | Initial after phone verification |
| Tier 2 | 10,000 unique users/day | 1,000/day for 7 consecutive days |
| Tier 3 | 100,000 unique users/day | 10,000/day for 7 consecutive days |
| Tier 4 | Unlimited | 100,000/day for 7 consecutive days |
Error Reference
| Code | Meaning | Action |
|---|---|---|
| 63001 | Recipient not opted in | Permanent failure — do not retry; flag for manual outreach |
| 63003 | Template not approved | Permanent failure — resubmit template or use different template |
| 63005 | Commerce policy violation | Permanent failure — review message content |
| 63007 | Number not registered on WhatsApp | Permanent failure — use SMS fallback |
| 63012 | 24h window expired, freeform blocked | Use template or wait for next inbound |
| 63032 | User opted out (STOP) | Permanent — remove from list, honor immediately |
| 20429 | Rate limit exceeded | Retryable — exp backoff 3x, alert ops |
| 20500 | Twilio internal error | Retryable — exp backoff 3x |
| 21211 | Invalid To phone number | Permanent failure — check E.164 format |
SMS/Carrier Compliance Cluster
WhatsApp sits alongside but separate from the domestic A2P 10DLC stack. Key distinctions:
| Dimension | WhatsApp (Meta/Twilio BSP) | SalesMsg | OpenPhone/Quo | Twilio Voice |
|---|---|---|---|---|
| Hub | This file | salesmsg | openphone-quo | twilio |
| Port | n/a (staging) | :18793 | :18792 | :18797 |
| Opt-in | Explicit Meta opt-in required | A2P 10DLC | A2P 10DLC | TCPA |
| Sig verification | HMAC-SHA1 (X-Twilio-Signature) | Query param token | HMAC | HMAC |
| Template required | Yes (business-initiated) | No | No | TwiML only |
| 24h window | Yes (Meta rule) | No | No | No |
| Status | Staging | Production | Production | Production |
See compliance-gates for cross-channel compliance gate logic.
Pre-implementation Checklist (Before Wiring)
Before WhatsApp goes to production, these items must be completed:
- Meta Business Manager account verified (business verification, not just app registration)
- WhatsApp Business Account (WABA) created and approved
- Production phone number added, verified, and quality-rated
- At least 1 UTILITY template approved by Meta
- Opt-in capture mechanism built and tested
- Webhook handler created at
workspace/webhooks/whatsapp-handler.jswith:- X-Twilio-Signature HMAC validation
processed_webhook_eventsdedup (24h TTL)webhook_audit_logwrite with local file fallback- STOP/UNSUBSCRIBE handler
- Endpoint registered in
workspace/FUNNEL-REGISTRY.md -
infra_config_changesrow written before going live (CHOKEPOINT-2) - Port registered in CLAUDE.md port map + ARCHITECTURE.md service table (G-SERVICE-PRE-START-DOC)
- Credentials stored in 1Password vault only — never plaintext (G-NO-PLAINTEXT-CREDS)
- Henry authorization obtained for new outbound channel (feedback_never_send_without_auth)
Cross-Links
Agents
- _summary — outbound messaging brain, channel selection, compliance gating
- _summary — acquisition outreach channel selection; decides SMS vs WhatsApp vs voice
Skills
- acquisitions-outreach — Stage 1 channel selection (5-gate compliance includes channel eligibility)
- acquisitions-followup — Stage 2-4 channel selection (escalation logic includes WhatsApp fallback)
Plans
- osil-twilio-10dlc-resubmission-2026-05-03 — 10DLC A2P resubmission blocking domestic SMS tier; WhatsApp deferral tied to this resolution
- nemoclaw-audit-2026-05-03 — L7 credential injection proxy (B1-B6); WhatsApp cred-proxy-eligible marked pending until ratified
Feedback rules
- feedback_aurora_outbound_guardrails — never send without passing compliance gate; applies to WhatsApp
- feedback_never_send_without_auth — Henry authorization required before activating any new outbound channel
- feedback_no_plaintext_creds — G-NO-PLAINTEXT-CREDS; all WhatsApp/Twilio creds via
op://Aurora/... - feedback_action_gate_violation_repeated — service restarts require explicit auth; applies to any new WhatsApp systemd unit
Related integration cluster
salesmsg · openphone-quo · twilio · cloudflare · compliance-gates
KB docs
knowledge-base/whatsapp/API.md— Twilio BSP endpoints, auth, webhook payloads, message status, error codes (last_verified: 2026-03-04)knowledge-base/whatsapp/_audit/2026-05-02.md— 53 findings: deprecation (on-prem EOL), feature gaps (HubSpot integration, Cloud API direct, opt-in flows, interactive messages)knowledge-base/whatsapp/_audit/2026-05-04.md— 0 findingsknowledge-base/twilio/— Twilio voice and SMS KB (shared BSP credentials)
System maps
- external-integrations — WhatsApp in the external integration topology
- deal-lifecycle-map — messaging channels in the deal lifecycle
Governance Gates in Effect
| Gate | Status | Notes |
|---|---|---|
| G-NO-PLAINTEXT-CREDS | Enforced | All creds as op://Aurora/<platform>/<field> — zero plaintext in this file |
| G-BLOCKER-SURFACING | Enforced | Open issues below must be mirrored to SESSION-AUDIT.md NEXT ACTIONS |
| G-SERVICE-PRE-START-DOC | Pending (pre-production) | No unit created yet; must register port + service before first start |
| FUNNEL-REGISTRY | Pending (pre-production) | /webhook/whatsapp path planned but not yet registered |
| CHOKEPOINT-1 | Required at launch | Every outbound message must write a tool_calls row |
| CHOKEPOINT-2 | Required at launch | infra_config_changes row required before going live |
Open Issues / TODOs
-
BSP vs Cloud API Direct decision (BLOCKER): Audit finding recommends evaluating Cloud API direct (lower cost, higher throughput, native HubSpot integration capability) vs continuing with Twilio BSP (consistent with existing Twilio voice/SMS stack). Requires Henry decision. See
_audit/2026-05-02.md§“WhatsApp Business Platform Cloud API (direct, not only via Twilio)“. -
HubSpot–WhatsApp native integration (BLOCKER candidate): Audit identifies native HubSpot WhatsApp integration (event-based workflows, CRM timeline sync, one-click messaging from deal views) as highest-ROI feature gap. Evaluate before building custom webhook handler to avoid parallel implementation.
-
10DLC dependency: WhatsApp deferral is intentional pending domestic SMS 10DLC resubmission resolution. Do not accelerate WhatsApp until domestic SMS compliance is clean.
-
Opt-in infrastructure: No opt-in capture mechanism exists. Required before any production messaging. Needs design (web form, QR, Click-to-WhatsApp ads).
-
Template library: Zero approved templates exist. UTILITY templates take ~24h for approval. Begin template creation well before any planned go-live.
-
2026 pricing update: Meta updated WhatsApp Business API pricing effective April 1, 2026. Cost estimates in this hub (inherited from KB last_verified 2026-03-04) may be stale. Verify current rates at twilio.com/pricing and meta for Developers before budgeting any campaign.
-
WhatsApp Calling API (2026): WhatsApp Business Calling API is now GA — businesses can initiate/receive voice calls directly in WhatsApp conversations through the API. Evaluate as a future channel for high-intent lead follow-up once messaging is live.
-
Interactive Media Carousel (2026): WhatsApp now supports 2-10 horizontally scrollable cards per message (no product catalog required). High-value for dispo property blasts — evaluate for buyer outreach once channel is active.
-
AI policy compliance (Jan 15, 2026): Aurora’s WhatsApp integration must be structured as task-specific flows (lead qualification, appointment scheduling, status updates) — not a general-purpose chatbot. Implement as bounded workflow templates, not open-ended conversation.
Recent Activity
| Date | Event |
|---|---|
| 2026-05-04 | Hub created (W3-S6). KB found at knowledge-base/whatsapp/. Status: staging. No production wiring. |
| 2026-05-04 | Audit run #10: 0 findings |
| 2026-05-02 | Audit run #3: 53 findings — on-prem EOL deprecation, Cloud API direct opportunity, HubSpot native integration gap, opt-in infrastructure missing |
| 2026-03-04 | KB API.md last verified — Twilio BSP path documented |
| n/a | No webhook handler, no outbound script, no production traffic |