Integrations / WhatsApp
WhatsApp (Twilio)
CloudyBot’s WhatsApp channel uses Twilio: a signed inbound webhook and outbound REST sends. Messages are tied to your CloudyBot userId through channel identity storage (including claim tokens where used). Inbound user messages run through the same agent path as dashboard chat (not a separate toy bot), then replies go back out via Twilio.
Use cases
- Chat from your phone: Ask your assistant on WhatsApp and get the same model and tool behavior your deployment allows for that user.
- Scheduled updates: Cron and other delivery paths can send WhatsApp when configured; proactive chunks are metered and carry opt-out language as described below.
- Operational alerts: Pair with scheduled duties or internal workflows that should ping a human on a known WhatsApp thread (subject to plan limits and opt-out).
WhatsApp is not on the Free tier for product positioning on the public pricing page; paid tiers include a published monthly proactive send allowance.
Setup flow (high level)
- Operator: Configure Twilio credentials and your WhatsApp sender—typically
TWILIO_ACCOUNT_SID,TWILIO_AUTH_TOKEN, andTWILIO_WHATSAPP_NUMBER(seeapi/.env.example). Optional:TWILIO_WEBHOOK_PUBLIC_URLso request signatures match the public URL;TWILIO_WEBHOOK_SKIP_SIGNATURE_VALIDATIONonly for non-production debugging. - Webhook: Point Twilio’s WhatsApp inbound webhook at your deployment’s
POST /webhooks/whatsappURL. - User: Complete the in-dashboard flow to link and claim your WhatsApp number to your CloudyBot account (channel users + claim tokens in the product database). Until identity is resolved, inbound handling may log warnings and fail to attach traffic to a user.
- After claim: The API records WhatsApp consent (E.164 phone, method such as
claim_flow) for auditability.
Plan-based proactive send cap
Proactive outbound WhatsApp is counted per user per billing period against whatsappSends in the plan map shipped with the API. On the default tier definitions: Free — 0; Growth — 100; Pro — 200; Max — 500 proactive sends per month. Your operator may override plan data—use Pricing and in-app usage for your account as source of truth.
Compliance, opt-out, and inbound keywords
- Proactive footer: When sending with proactive mode, chunks include “Reply STOP to unsubscribe.” The stack enforces proactive opt-out state and plan quota before sending, then increments the proactive counter after each successful metered send.
- Opt-out keywords (standalone inbound): STOP, UNSUBSCRIBE, CANCEL, END, QUIT, or STOPALL record proactive opt-out. START clears proactive opt-out. A successful channel claim also clears proactive opt-out state.
- Not marketing opt-out: Phrases like stop browser, browser stop, or stop session are interpreted as browser session end commands, not SMS unsubscribe.
- Cron nuance: Scheduled delivery uses
meterProactive: trueon every chunk andproactive: trueonly on the last chunk so the unsubscribe footer appears once per logical message while metering applies throughout.
More policy context lives in api/features/compliance/README.md (§7) in the repository.
FAQ
How does inbound WhatsApp work?
Twilio POSTs to /webhooks/whatsapp. The API validates the Twilio signature (unless explicitly disabled in non-production), resolves your CloudyBot user via channel identity helpers, applies rate limits and moderation, then runs the same async path as dashboard chat toward the agent stack (sendToOpenClaw for WhatsApp) and replies using outbound Twilio REST (sendWhatsAppMessage). This is not a separate lightweight bot—it is the same product stack with channel attribution.
What are proactive WhatsApp sends and how are they limited?
Proactive messages are outbound chunks sent with proactive tooling: copy includes “Reply STOP to unsubscribe.” on proactive chunks, the system enforces proactive opt-out and plan quota, and increments the monthly proactive send counter after each successful metered send. Scheduled (cron) delivery uses meterProactive on every chunk and proactive true on the last chunk only. Free plans include no proactive WhatsApp allowance; standard self-serve paid tiers publish fixed monthly caps (Growth 100, Pro 200, Max 500 proactive sends in the shipped plan map—confirm on Pricing if your operator customizes).
How do STOP, START, and related keywords work?
Standalone inbound messages STOP, UNSUBSCRIBE, CANCEL, END, QUIT, or STOPALL record a proactive WhatsApp opt-out. START clears that opt-out. Separately, phrases like stop browser, browser stop, or stop session are handled as browser session end commands—not SMS marketing opt-out. Opt-out state is cleared when a user completes a successful channel claim, per the channels feature design.
What compliance records exist when I link WhatsApp?
After a successful claim of your WhatsApp number to your CloudyBot user, the API records WhatsApp consent (phone in E.164, method such as claim_flow, audit row in whatsapp_consents). Proactive opt-outs live in whatsapp_proactive_opt_outs. Proactive send counts are tracked in whatsapp_sends per user and billing period. Together these support Meta-style policy and troubleshooting; they are not a substitute for your own legal review.
Link WhatsApp from the dashboard when your workspace has the channel enabled.
Open dashboardReview plan limits before relying on proactive volume.