OpenClaw Twilio WhatsApp Channel

> ⚠️ Install via a coding agent — not via the standard OpenClaw install flow. > This plugin is non-trivial to deploy: it requires a Twilio account, a public HTTPS URL, environment-variable secrets, exact webhook-URL matching, and gateway version >= 2026.5.26. The ClawHub one-click install will leave you with a half-configured plugin that silently 403s or 404s. > > Preferred path: point a coding agent (Claude Code, Cursor, etc.) at AGENT_INSTRUCTIONS.md and have it walk you through setup. The ClawHub listing exists for discoverability — not as a supported install path.

A channel plugin for OpenClaw that connects your AI agent to WhatsApp via the Twilio Business API.

 

Why Twilio over Baileys?

OpenClaw ships with a built-in WhatsApp channel based on Baileys, which reverse-engineers the WhatsApp Web protocol. Baileys is convenient — no business verification, no monthly fees — but the trade-offs are real:

| Concern | Baileys | Twilio (this plugin) | |---|---|---| | Protocol stability | Breaks when WhatsApp changes their internal protocol | Official, versioned API | | Account safety | Risk of bans for "automated" behavior | Compliant Business API | | Delivery receipts | Best-effort | First-class status callbacks | | Group messaging | Yes | No (1:1 DMs only) | | Cost | Free | Per-message fees | | Setup | QR-code pairing | Sender registration + webhook |

Pick this plugin when you need stability and compliance — for personal automations or when you need group chat, the bundled Baileys channel is simpler.

Features

• Inbound webhooks via OpenClaw's gateway (no separate HTTP server)
• Twilio signature validation on every inbound request
• Allowlist enforcement so only approved phone numbers can talk to your agent
• Inbound media download with redirect-following Basic Auth
• Outbound media staging — local files are served back to Twilio via UUID-randomized URLs
• Message chunking at Twilio's 1600-char limit
• WhatsApp formatting hints injected into the agent prompt (bold, _italic_, etc.)
• Fire-and-forget webhook responses — TwiML returned immediately, processing happens async (avoids Twilio's 15s timeout)

Installation

See AGENT_INSTRUCTIONS.md. Point a coding agent at it and have it walk you through the install — Twilio sender setup, public webhook URL, gateway-side plugin install, openclaw.json config, env-var secrets, and verification. The agent will collect the inputs from you, generate the right config for your deployment shape (Docker / Compose / k8s), and avoid the common foot-guns (legacy config shape, wrong container UID, etc.).

The standard ClawHub one-click install is not sufficient for this plugin — the listing exists for discoverability. The plugin needs out-of-band configuration that ClawHub doesn't collect.

Configuration reference

The agent install will write these for you — this section is for reference only.

openclaw.json — channels.twilio-whatsapp

| Field | Required | Description | |---|---|---| | enabled | yes | Activate the channel | | dmPolicy | yes | "allowlist" (only allowFrom numbers) or "open" (anyone) | | allowFrom | when allowlist | Phone numbers in E.164 format (e.g. +14155551234) | | fromNumber | yes | Your Twilio WhatsApp sender in E.164 | | webhookUrl | yes | Public base URL where Twilio can reach OpenClaw — used both for signature validation and media serving | | textChunkLimit | no (default 1600) | Max characters per outbound message before splitting (Twilio rejects > 1600 with error 21617) | | chunkMode | no (default length) | "length" or "newline" — prefer paragraph boundaries when splitting |

All phone numbers use E.164 format without the whatsapp: prefix — the plugin prepends it internally when calling Twilio.

Modern OpenClaw gateways key plugin config by the manifest id twilio-whatsapp (not the npm package name) in plugins.allow / plugins.entries. The legacy plugins.load.paths field is no longer used — plugin install paths are auto-discovered. See AGENT_INSTRUCTIONS.md for the exact openclaw.json shape.

Environment variables (secrets)

| Variable | Required | Description | |---|---|---| | TWILIO_ACCOUNT_SID | yes | Your Twilio account SID (starts with AC) | | TWILIO_AUTH_TOKEN | yes | Your Twilio auth token |

Twilio setup

1. Get a WhatsApp sender

For development, use the Twilio Sandbox for WhatsApp. For production, register a WhatsApp sender.

2. Configure the inbound webhook

In the Twilio Console for your WhatsApp sender, set:

• When a message comes in: https://<your-host>/webhook/twilio-whatsapp
• Method: HTTP POST

The path is fixed by this plugin. The host must match webhookUrl in your OpenClaw config exactly — Twilio's signature validation requires the URL to match.

3. Verify the health endpoint

curl https://<your-host>/webhook/twilio-whatsapp/health
# {"status":"ok","channel":"twilio-whatsapp"}

4. Send a test message

WhatsApp the number you registered in fromNumber from a phone in your allowFrom list. The agent should reply.

Architecture

┌─────────────────┐      POST /webhook/twilio-whatsapp
│  Twilio API     │ ──────────────────────────────────► ┌──────────────────┐
│                 │ ◄────────── 200 TwiML <Response/> ── │ OpenClaw gateway │
└─────────────────┘                                      │  (this plugin)   │
        ▲                                                └────────┬─────────┘
        │  client.messages.create({...})                          │ dispatchInboundDirectDmWithRuntime
        │                                                         ▼
┌───────┴─────────┐                                       ┌──────────────┐
│ Outbound:       │ ◄──────────── deliver(payload) ────── │ Agent runtime│
│ sendText /      │                                       └──────────────┘
│ sendMedia       │
└─────────────────┘

HTTP routes registered

| Path | Auth | Purpose | |---|---|---| | POST /webhook/twilio-whatsapp | plugin (signature-validated) | Inbound from Twilio | | GET /webhook/twilio-whatsapp/media/* | plugin | Serves outbound media for Twilio to fetch | | GET /webhook/twilio-whatsapp/health | plugin | Liveness check |

Media handling

Inbound media (Twilio → agent):

• Downloaded with redirect-following Basic Auth
• Saved to ~/.openclaw/media/twilio-whatsapp/inbound/<MessageSid>-<i><ext>
• Path included in the MediaPath / MediaPaths envelope fields

Outbound media (agent → Twilio):

• Local files are copied to ~/.openclaw/media/twilio-whatsapp/outbound/<uuid><ext>
• Served via the media endpoint with parent-directory check (no traversal)
• Twilio fetches the URL and forwards to WhatsApp

Inbound flow

1. Twilio POSTs application/x-www-form-urlencoded body with Body, From, MessageSid, NumMedia, etc. 2. Plugin validates X-Twilio-Signature against webhookUrl + path — rejects with 403 on mismatch 3. Plugin checks From against allowFrom (with whatsapp: prefix stripped) — rejects with 403 if not allowed 4. Plugin immediately responds with empty TwiML (<Response/>) so Twilio doesn't time out 5. Plugin downloads any inbound media (async, after responding) 6. Plugin calls dispatchInboundDirectDmWithRuntime with the message envelope 7. Agent processes the message and sends a reply via sendText / sendMedia

Development

git clone https://github.com/srinathh/openclaw-channel-twilio-whatsapp.git
cd openclaw-channel-twilio-whatsapp
npm install
npm run build

Project layout

src/
├── index.ts          # defineChannelPluginEntry — plugin entry point
├── channel.ts        # createChatChannelPlugin — main plugin definition
├── webhook.ts        # Twilio webhook handler (signature validation + dispatch)
├── media.ts          # download / stage / serve media
├── runtime.ts        # createPluginRuntimeStore — runtime accessor for dispatch
├── util.ts           # phone formatting + form body parsing
└── openclaw-sdk.d.ts # ambient type declarations for openclaw/plugin-sdk/*

Testing locally

You'll need an OpenClaw instance running with this plugin installed. The simplest setup:

# 1. In one terminal: build and link
npm run build
npm link

# 2. In your OpenClaw instance directory
npm link @srinathh/openclaw-channel-twilio-whatsapp

# 3. Add to your openclaw.json plugins config (see Configuration)
# 4. Use a tunnel (cloudflared, ngrok) to expose the gateway
# 5. Point Twilio's webhook at the tunnel URL

Compatibility

• OpenClaw gateway: requires >= 2026.5.26. The plugin technically loads against >= 2026.3.28 (when the plugin-sdk/* subpath imports were introduced), but earlier 2026.x gateways have a core-side EACCES mkdir '/home/openclaw' bug that silently breaks outbound media — text replies arrive, images don't.
• OpenClaw operator (k8s): requires v0.30.0+ for the plugin peerDependency symlink
• Node.js: 20+

Known limitations

• DMs only — no group chat (Twilio's WhatsApp Business API doesn't support groups)
• No reactions / typing indicators — Twilio doesn't expose these
• No threaded replies — WhatsApp threading not exposed by Twilio
• Single account — multiple Twilio accounts aren't supported in this version

License

Apache-2.0 — see LICENSE.

Contributing

Issues and PRs welcome at github.com/srinathh/openclaw-channel-twilio-whatsapp.