Voice
Whatsapp Twilio
By The missing OpenClaw channel: bidirectional WhatsApp + SMS via the official Twilio API. Sandbox-to-Production in one config flag. MIT.
Install
npm install
npmREADME
# openclaw-whatsapp-twilio
> **The missing channel.** OpenClaw agents talking to the world's most-used messaging platform — through the most-trusted enterprise telecom on the planet.
[](https://www.npmjs.com/package/openclaw-whatsapp-twilio)
[](./LICENSE)
[](./dist/index.d.ts)
[](https://openclaw.ai)
A first-class OpenClaw channel plugin that connects your agents to **WhatsApp** and **SMS** through the official **Twilio API** — production-grade, signature-verified, and shipping in two channels at once.
```
user → WhatsApp → Twilio webhook → OpenClaw gateway → your agent → reply → Twilio → WhatsApp → user
```
That's it. No QR codes. No browser session that breaks at 3am. No reverse-engineered protocols. **Just the API Meta themselves bless.**
---
## Why this exists
Before this plugin, OpenClaw shipped exactly one WhatsApp integration: **Baileys-based**, riding WhatsApp Web. It works — until it doesn't. Numbers get rate-limited. Sessions get severed when you scan a new device. There is no SLA, no escalation, no path to scale beyond personal use.
The Twilio path is what every WhatsApp Business customer actually runs in production. Stripe runs on it. DoorDash runs on it. Now your OpenClaw agent runs on it too.
| | Baileys (`@openclaw/whatsapp`) | **`openclaw-whatsapp-twilio`** |
| --- | --- | --- |
| Transport | WhatsApp Web (reverse-engineered) | Official Twilio Programmable Messaging API |
| Setup | Scan QR with phone | Free Sandbox in 60s, then upgrade to Business |
| Rate limits | Your personal number's quota | Twilio's commercial quota |
| Risk of ban | Real (TOS gray zone) | Zero (official API) |
| SMS support | No | Yes — same plugin, same config |
| Cost at scale | Your phone bill | Per-message Twilio pricing |
| Webhook security | N/A | HMAC-SHA1 signature, constant-time compare |
| Status callbacks | No | Yes (planned v0.2) |
| Templates (outside 24h window) | No | Yes (`whatsapp_send_template`) |
If you want to **talk to one friend**, run Baileys.
If you want to **build a product** — this plugin.
---
## What it ships
- 🟢 **Two channels in one plugin**: `whatsapp-twilio` and `sms-twilio`. Same Twilio account, two transports, one config.
- 🟢 **Inbound webhook** with X-Twilio-Signature verification (HMAC-SHA1, constant-time compare).
- 🟢 **Outbound text + media** routed through OpenClaw's shared `message` tool.
- 🟢 **Outbound agent tools** — `whatsapp_send_message`, `whatsapp_send_media`, `whatsapp_send_template`, `sms_send_message` — when you need to push a message outside an active session.
- 🟢 **Allowlist DM policy** (E.164 number list) so test bots don't get scraped the day after you deploy.
- 🟢 **Multi-account**: define `channels.whatsapp-twilio.accounts.<id>` and the plugin keeps them separated, with per-account `fromNumber` and allowlists.
- 🟢 **Env-first secrets**: `accountSid` and `authToken` resolve from env when not in config, so they never accidentally land in version control.
- 🟢 **Sandbox-to-Production** with one config flag (`mode: "sandbox" | "business"`).
---
## Install
```bash
openclaw plugins install clawhub:openclaw-whatsapp-twilio
```
Or directly from npm during the launch cutover:
```bash
openclaw plugins install openclaw-whatsapp-twilio
```
Requirements:
- **Node 22.19+** (matches OpenClaw 2026.6 baseline)
- **OpenClaw 2026.6.1+** as peer dependency
- A **Twilio account** ([sign up — free trial credits](https://www.twilio.com/try-twilio))
- A **public HTTPS URL** that can reach your OpenClaw gateway (use Cloudflare Tunnel, ngrok, or your own domain)
---
## Quickstart: WhatsApp Sandbox in 60 seconds
This is the fastest possible loop: send a real WhatsApp message to your agent without setting up a verified business number.
### 1. Grab your Twilio credentials
From [console.twilio.com](https://console.twilio.com):
- **Account SID** (starts with `AC...`)
- **Auth Token** (the one labeled "Live Auth Token")
### 2. Join the WhatsApp Sandbox
[console.twilio.com/develop/sms/try-it-out/whatsapp-learn](https://console.twilio.com/develop/sms/try-it-out/whatsapp-learn) — send the join code (e.g. `join orange-tiger`) from your phone to the sandbox number `+1 415 523 8886`.
### 3. Configure OpenClaw
Add to your OpenClaw config:
```json5
{
plugins: {
entries: {
"whatsapp-twilio": {
config: {
accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
authToken: "your_auth_token",
validateSignature: true,
},
},
},
},
channels: {
"whatsapp-twilio": {
enabled: true,
mode: "sandbox",
fromNumber: "whatsapp:+14155238886",
webhookBaseUrl: "https://your-public-url.example.com",
dmPolicy: "allowlist",
allowFrom: ["+5491138952610"], // your own number
},
},
}
```
Or use env vars (and skip the secrets in config):
```bash
export TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export TWILIO_AUTH_TOKEN="your_auth_token"
export TWILIO_FROM_WHATSAPP="whatsapp:+14155238886"
export TWILIO_WEBHOOK_BASE_URL="https://your-public-url.example.com"
export TWILIO_ALLOWED_NUMBERS="+5491138952610"
```
### 4. Point Twilio at your gateway
In the Twilio console → WhatsApp Sandbox Settings → **"When a message comes in"**:
```
POST https://your-public-url.example.com/whatsapp-twilio/webhook
```
### 5. Start the gateway
```bash
openclaw gateway
```
Open WhatsApp on your phone and send a message to `+1 415 523 8886`. Your agent answers.
---
## Expose your gateway publicly
Twilio needs an HTTPS URL it can POST to. Three good options:
### Cloudflare Tunnel (recommended for dev)
```bash
brew install cloudflared
cloudflared tunnel --url http://localhost:8080
```
Cloudflare prints a `*.trycloudflare.com` URL — paste it into `TWILIO_WEBHOOK_BASE_URL` and the Twilio console.
### ngrok
```bash
ngrok http 8080
```
### Your own domain
If your OpenClaw gateway already lives on a public box, point a subdomain at it and put nginx/Caddy in front for HTTPS.
---
## Going to production: WhatsApp Business API
The sandbox is for testing. For real customers you need a verified WhatsApp Business Sender.
1. In Twilio Console → **Messaging → Senders → WhatsApp** → "Request access"
2. Provide your business legal name, Meta Business Manager ID, and a verified phone number
3. Wait for Meta's approval (24h – 14d depending on region/category)
4. Once approved, swap your config:
```json5
{
channels: {
"whatsapp-twilio": {
mode: "business",
fromNumber: "whatsapp:+15014493684", // your real number
// everything else stays the same
},
},
}
```
Restart the gateway. Same code, same webhook, real customers.
---
## SMS in 30 seconds
The same plugin, same Twilio account, second channel:
```json5
{
channels: {
"sms-twilio": {
enabled: true,
fromNumber: "+15014493684",
webhookBaseUrl: "https://your-public-url.example.com",
dmPolicy: "allowlist",
allowFrom: ["+5491138952610"],
},
},
}
```
In Twilio Console → Phone Numbers → your number → "A message comes in":
```
POST https://your-public-url.example.com/sms-twilio/webhook
```
Your agent now talks SMS too.
---
## Agent tools
Beyond the shared OpenClaw `message` tool (which the agent uses for normal replies), this plugin also registers four direct-action tools so an agent can initiate messages on its own:
### `whatsapp_send_message`
Send a free-form WhatsApp message. Only works within a 24-hour active session.
```typescript
{
to: "+5491138952610",
text: "Tu pedido fue despachado.",
}
```
### `whatsapp_send_media`
Send up to 10 media files (images, audio, video, documents) by HTTPS URL.
```typescript
{
to: "+5491138952610",
mediaUrls: ["https://my-cdn.com/invoice.pdf"],
caption: "Tu factura de marzo.",
}
```
### `whatsapp_send_template`
Send a pre-approved template message — required to start a new conversation outside the 24-hour session window.
```typescript
{
to: "+5491138952610",
contentSid: "HXabc123def456...", // from Twilio Content API
contentVariables: { "1": "Mariano", "2": "Reserva 12345" },
}
```
### `sms_send_message`
Send an SMS. No session window — works 24/7.
```typescript
{
to: "+5491138952610",
text: "Tu código de verificación es 482914.",
}
```
---
## Architecture
```
┌─────────────────────────────────────────────────┐
│ Twilio Cloud │
│ WhatsApp Cloud Connector + SMS gateway │
└───────────────┬─────────────────┬───────────────┘
│ │
POST │ │ REST
X-Twilio-Sig: │ │
▼ ▲
┌──────────────────────────────────────────────────────────┐
│ openclaw-whatsapp-twilio │
│ │
│ /whatsapp-twilio/webhook api.registerHttpRoute │
│ /sms-twilio/webhook api.registerHttpRoute │
│ │
│ signature.ts ──────► HMAC-SHA1 constant-time verify │
│ webhook.ts ──────► parse, allowlist, dispatch │
│ channel.ts ──────► createChatChannelPlugin × 2 │
│ client.ts ──────► POST Messages.json (Basic Auth) │
│ tools.ts ──────► send_message / send_media / ... │
└──────────────────────────┬──────────────────────────────
... (truncated)
voice
Comments
Sign in to leave a comment