OpenClaw Twilio WhatsApp Channel

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

This plugin is loaded by OpenClaw at runtime via npm. Add it to your OpenClawInstance CRD:

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: openclaw
spec:
  plugins:
    - "@srinathh/openclaw-channel-twilio-whatsapp@latest"

Or in a non-Kubernetes deployment, install it into your OpenClaw runtime's node_modules:

npm install @srinathh/openclaw-channel-twilio-whatsapp@latest

Then add it to the plugins.load.paths array in openclaw.json (see Configuration).

Configuration

openclaw.json

{
  "channels": {
    "twilio-whatsapp": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+14155551234", "+14155555678"],
      "fromNumber": "+14155550000",
      "webhookUrl": "https://your-public-host.example.com"
    }
  },
  "plugins": {
    "enabled": true,
    "allow": ["@srinathh/openclaw-channel-twilio-whatsapp"],
    "load": {
      "paths": ["~/.openclaw/node_modules/@srinathh/openclaw-channel-twilio-whatsapp"]
    },
    "entries": {
      "@srinathh/openclaw-channel-twilio-whatsapp": { "enabled": true }
    }
  }
}

| 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 |

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

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: requires openclaw >= 2026.3.28 (uses the plugin-sdk/* subpath imports)
• 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.