@elizaos/plugin-whatsapp 2.0.0-beta.1 → 2.0.3-beta.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,50 +1,28 @@
-# plugin-whatsapp
+# @elizaos/plugin-whatsapp
 
-WhatsApp plugin for ElizaOS. Supports both WhatsApp Cloud API and Baileys (QR authentication), enabling agents to send and receive messages, media, reactions, and interactive content via WhatsApp.
+WhatsApp plugin for elizaOS. Connects Eliza agents to WhatsApp via the **WhatsApp Cloud API** (Meta Business) or **Baileys** (personal account / QR-code auth).
 
-## Features
+## Capabilities
 
-- **Text Messages**: Send and receive text messages with URL preview
-- **Media Messages**: Send images, videos, audio, documents, and stickers
-- **Reactions**: Send and remove emoji reactions on messages
-- **Interactive Messages**: Send button and list messages for rich interactions
-- **Location Messages**: Share location data with name and address
-- **Template Messages**: Send pre-approved message templates
-- **Webhooks**: Handle incoming messages and status updates
-- **Baileys QR Auth**: Connect personal WhatsApp accounts with QR login + session persistence
-- **Message Status**: Track sent, delivered, read, and failed statuses
-- **Media Downloads**: Retrieve media URLs for incoming messages
+- Send and receive text messages (inbound messages ingested into agent memory)
+- Send emoji reactions, remove reactions
+- Support for media captions (image, video, document) on inbound messages
+- Interactive message content extraction (button replies, list replies)
+- Location and reaction message handling
+- Baileys QR-code pairing with session persistence
+- Multi-account support (multiple WhatsApp numbers per agent)
+- DM and group access policies (open / allowlist / pairing / disabled)
+- Webhook verification and `X-Hub-Signature-256` security for Cloud API
 
 ## Installation
 
-### TypeScript
-
 ```bash
 npm install @elizaos/plugin-whatsapp
 ```
-## Configuration
 
-### Environment Variables
+## Enabling the Plugin
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WHATSAPP_ACCESS_TOKEN` | Yes | WhatsApp Business API access token |
-| `WHATSAPP_PHONE_NUMBER_ID` | Yes | Phone number ID from WhatsApp Business API |
-| `WHATSAPP_WEBHOOK_VERIFY_TOKEN` | No | Token for webhook verification |
-| `WHATSAPP_BUSINESS_ACCOUNT_ID` | No | Business account ID |
-| `WHATSAPP_API_VERSION` | No | Graph API version (default: v24.0) |
-| `WHATSAPP_AUTH_METHOD` | No | `cloudapi` or `baileys` (auto-detected if omitted) |
-| `WHATSAPP_AUTH_DIR` | No | Path for Baileys multi-file auth state |
-| `WHATSAPP_SESSION_PATH` | No | Alternative to `WHATSAPP_AUTH_DIR` for Baileys auth state |
-| `WHATSAPP_PRINT_QR` | No | Print QR in terminal for Baileys auth (default: true) |
-| `WHATSAPP_DM_POLICY` | No | DM handling policy: `open`, `allowlist`, `pairing`, or `disabled` |
-| `WHATSAPP_GROUP_POLICY` | No | Group handling policy: `open`, `allowlist`, or `disabled` |
-| `WHATSAPP_ALLOW_FROM` | No | Comma-separated allowlist for DM senders (when DM policy is `allowlist`) |
-| `WHATSAPP_GROUP_ALLOW_FROM` | No | Comma-separated allowlist for group senders (when group policy is `allowlist`) |
-
-### TypeScript Configuration
-
-The plugin self-registers `WhatsAppConnectorService` on the elizaOS runtime and reads its config from runtime settings / environment variables — no manual construction is required. Just register the default export on your character/agent:
+Add the plugin to your character file:
 
 ```typescript
 import whatsappPlugin from "@elizaos/plugin-whatsapp";
@@ -55,228 +33,143 @@ export const character = {
 };
 ```
 
-The service picks up `WHATSAPP_ACCESS_TOKEN` + `WHATSAPP_PHONE_NUMBER_ID` (Cloud API) or `WHATSAPP_AUTH_DIR` (Baileys / QR) automatically. See the env-var table above.
+The plugin also auto-enables when a `connectors.whatsapp` block is present in agent config.
 
-To access the service at runtime (e.g. to send a message from your own code):
+## Configuration
 
-```typescript
-import type { WhatsAppConnectorService } from "@elizaos/plugin-whatsapp";
+### Cloud API (Meta Business)
 
-const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
-await service?.sendMessage({ type: "text", to: "+14155552671", content: "hello" });
-```
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `WHATSAPP_ACCESS_TOKEN` | Yes | Long-lived access token from Meta Business Manager |
+| `WHATSAPP_PHONE_NUMBER_ID` | Yes | Phone number ID registered in Meta Business |
+| `WHATSAPP_APP_SECRET` | Yes (webhooks) | App Secret for `X-Hub-Signature-256` verification on incoming webhook POSTs |
+| `WHATSAPP_WEBHOOK_VERIFY_TOKEN` | No | Token for Meta's one-time GET webhook subscribe handshake |
+| `WHATSAPP_BUSINESS_ACCOUNT_ID` | No | WABA ID (informational only) |
+| `WHATSAPP_API_VERSION` | No | Graph API version string (default: `v24.0`) |
 
-## Usage
+### Baileys (personal account / QR auth)
 
-### Sending Messages
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `WHATSAPP_AUTH_DIR` | Yes (Baileys) | Directory to persist multi-file Baileys auth state |
+| `WHATSAPP_SESSION_PATH` | No | Alternative name for `WHATSAPP_AUTH_DIR` |
+| `WHATSAPP_AUTH_METHOD` | No | Force transport: `cloudapi` or `baileys` (overrides auto-detection) |
 
-The TypeScript snippets below use two variables:
+**Transport detection:** `WHATSAPP_AUTH_METHOD` wins when set. Otherwise: `WHATSAPP_AUTH_DIR` present → Baileys; `WHATSAPP_ACCESS_TOKEN` + `WHATSAPP_PHONE_NUMBER_ID` present → Cloud API. Baileys takes precedence when both are set.
 
-- `service` — the registered `WhatsAppConnectorService`, obtained via `runtime.getService<WhatsAppConnectorService>("whatsapp")`. This is the recommended path: it routes through the same auth + policy stack the agent uses for incoming messages.
-- `client` — the underlying low-level client (`IWhatsAppClient`), used only for advanced media APIs not exposed on the service. Construct one with the exported `ClientFactory.create({ accessToken, phoneNumberId })` (Cloud API) or `ClientFactory.create({ authDir })` (Baileys) — the concrete `WhatsAppClient` / `BaileysClient` classes are internal.
+### Access Control
 
-#### Text Message
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WHATSAPP_DM_POLICY` | `pairing` | `open`, `allowlist`, `pairing`, or `disabled` |
+| `WHATSAPP_GROUP_POLICY` | `allowlist` | `open`, `allowlist`, or `disabled` |
+| `WHATSAPP_ALLOW_FROM` | — | Comma-separated E.164 numbers allowed in DMs (when policy is `allowlist`) |
+| `WHATSAPP_GROUP_ALLOW_FROM` | — | Comma-separated E.164 numbers allowed as group senders |
 
-**TypeScript**:
-```typescript
-const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
-await service?.sendMessage({ type: "text", to: "1234567890", content: "Hello, World!" });
-```
+### Agent Behavior
 
-**Python**:
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WHATSAPP_AUTO_REPLY` | `false` | When `true`, inbound messages trigger automatic agent replies. Off by default — messages are stored in memory only |
 
-**Rust**:
+## Usage
 
-#### Image Message
+### Accessing the Service
 
-**TypeScript**:
 ```typescript
-await client.sendImage('1234567890', 'https://example.com/image.jpg', 'Caption');
-```
-
-**Python**:
+import type { WhatsAppConnectorService } from "@elizaos/plugin-whatsapp";
 
-**Rust**:
+const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
+```
 
-#### Interactive Button Message
+### Sending a Text Message
 
-**TypeScript**:
 ```typescript
-await client.sendButtonMessage(
-    '1234567890',
-    'Choose an option:',
-    [
-        { id: 'opt1', title: 'Option 1' },
-        { id: 'opt2', title: 'Option 2' },
-        { id: 'opt3', title: 'Option 3' },
-    ],
-    'Header Text',
-    'Footer Text'
-);
+await service?.sendMessage({
+  type: "text",
+  to: "+14155552671",  // E.164 format for Cloud API; JID or E.164 for Baileys
+  content: "Hello from elizaOS!",
+});
 ```
 
-**Python**:
-
-**Rust**:
+### Sending a Message with Reply Threading
 
-### Sending Reactions
-
-**TypeScript**:
 ```typescript
-await client.sendReaction({
-    to: '1234567890',
-    messageId: 'wamid.xxx',
-    emoji: '👍',
+await service?.sendMessage({
+  type: "text",
+  to: "+14155552671",
+  content: "This is a reply",
+  replyToMessageId: "wamid.xxxxx",
 });
-
-// Remove reaction
-await client.removeReaction('1234567890', 'wamid.xxx');
 ```
 
-**Python**:
-
-**Rust**:
+### Creating a Low-Level Client
 
-### Handling Webhooks
+Use `ClientFactory` when you need direct access to Cloud API media endpoints:
 
-**TypeScript**:
 ```typescript
-import express from 'express';
+import { ClientFactory } from "@elizaos/plugin-whatsapp";
 
-const app = express();
+// Cloud API
+const client = ClientFactory.create({ accessToken: "...", phoneNumberId: "..." });
 
-const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
+// Baileys
+const client = ClientFactory.create({ authMethod: "baileys", authDir: "./wa-auth" });
+```
 
-// Verification endpoint
-app.get('/webhook', (req, res) => {
-    const mode = String(req.query['hub.mode'] ?? '');
-    const token = String(req.query['hub.verify_token'] ?? '');
-    const challenge = String(req.query['hub.challenge'] ?? '');
-
-    const reply = service?.verifyWebhook(mode, token, challenge);
-    if (reply) {
-        res.status(200).send(reply);
-    } else {
-        res.sendStatus(403);
-    }
-});
+### Webhook Setup (Cloud API)
 
-// Message handling endpoint
-app.post('/webhook', express.json(), async (req, res) => {
-    await service?.handleWebhook(req.body);
-    res.sendStatus(200);
-});
-```
+The plugin automatically registers these HTTP routes on the agent:
 
-**Python**:
+- `GET /api/whatsapp/webhook` — Meta subscription verification (public)
+- `POST /api/whatsapp/webhook` — Incoming message delivery (validates `X-Hub-Signature-256`)
 
-**Rust**:
+Point your Meta App webhook URL to `https://<your-agent-host>/api/whatsapp/webhook`.
 
-### Event Handling
+### QR Pairing (Baileys)
 
-**TypeScript** (using event emitter pattern):
-```typescript
-// Events are emitted by the webhook handler
-webhookHandler.onMessage((message) => {
-    console.log('Message received:', message);
-});
+Start a pairing session via the agent's HTTP API:
 
-webhookHandler.onStatus((status) => {
-    console.log('Status update:', status);
-});
+```bash
+# Start pairing
+curl -X POST http://localhost:31337/api/whatsapp/pair \
+  -H "Content-Type: application/json" \
+  -d '{"accountId": "default"}'
+
+# Check status
+curl http://localhost:31337/api/whatsapp/status?accountId=default
+
+# Stop pairing
+curl -X POST http://localhost:31337/api/whatsapp/pair/stop \
+  -H "Content-Type: application/json" \
+  -d '{"accountId": "default"}'
+
+# Logout and remove auth state
+curl -X POST http://localhost:31337/api/whatsapp/disconnect \
+  -H "Content-Type: application/json" \
+  -d '{"accountId": "default"}'
 ```
 
-**Python**:
-
-**Rust**:
-
-## Actions
-
-WhatsApp messaging is exposed through the canonical message connector actions.
-Use `source: "whatsapp"` when a request needs to target WhatsApp explicitly.
-Media, templates, and interactive messages remain available through the service
-and low-level client APIs shown above; they are not advertised as separate
-executable action names.
-
-| Primary action | Operation | Description |
-|----------------|-----------|-------------|
-| `MESSAGE` | `send` | Send a message to a phone number, contact, user, group, or room |
-| `MESSAGE` | `read` | Read recent WhatsApp conversation messages |
-| `MESSAGE` | `search` | Search WhatsApp conversation history |
-| `MESSAGE` | `react` | Send or remove a reaction on a message |
-| `MESSAGE` | `get_user` | Resolve a WhatsApp contact or user |
-
-## Event Types
-
-| Event | Description |
-|-------|-------------|
-| `MESSAGE_RECEIVED` | New message received |
-| `MESSAGE_SENT` | Message was sent |
-| `MESSAGE_DELIVERED` | Message was delivered |
-| `MESSAGE_READ` | Message was read |
-| `MESSAGE_FAILED` | Message delivery failed |
-| `REACTION_RECEIVED` | Reaction received on a message |
-| `REACTION_SENT` | Reaction was sent |
-| `INTERACTIVE_REPLY` | User replied to interactive message |
-| `WEBHOOK_VERIFIED` | Webhook was verified |
-
-## Common Reactions
-
-The plugin provides constants for common reaction emojis:
-
-| Name | Emoji |
-|------|-------|
-| `THUMBS_UP` | 👍 |
-| `THUMBS_DOWN` | 👎 |
-| `HEART` | ❤️ |
-| `LAUGHING` | 😂 |
-| `SURPRISED` | 😮 |
-| `SAD` | 😢 |
-| `PRAYING` | 🙏 |
-| `CLAPPING` | 👏 |
-| `FIRE` | 🔥 |
-| `CELEBRATION` | 🎉 |
-
-## API Reference
-
-### WhatsAppClient / WhatsAppService
-
-| Method | Description |
-|--------|-------------|
-| `sendTextMessage(to, text)` | Send a text message |
-| `sendImage(to, url, caption?)` | Send an image |
-| `sendVideo(to, url, caption?)` | Send a video |
-| `sendAudio(to, url)` | Send audio |
-| `sendDocument(to, url, filename?, caption?)` | Send a document |
-| `sendLocation(to, lat, lng, name?, address?)` | Send a location |
-| `sendReaction(params)` | Send a reaction |
-| `removeReaction(to, messageId)` | Remove a reaction |
-| `sendButtonMessage(to, body, buttons, header?, footer?)` | Send button message |
-| `sendListMessage(to, body, buttonText, sections, header?, footer?)` | Send list message |
-| `markMessageAsRead(messageId)` | Mark a message as read |
-| `getMediaUrl(mediaId)` | Get download URL for media |
-| `verifyWebhook(token)` | Verify webhook token |
+## Multi-Account
 
-## Troubleshooting
+Configure multiple WhatsApp accounts under `character.settings.whatsapp.accounts.<id>`. Each entry accepts the same fields as the top-level config (`authDir`, `accessToken`, `phoneNumberId`, `dmPolicy`, `groupPolicy`, etc.) plus an optional `name` for display.
 
-### Common Issues
+## Message Connector Protocol
 
-1. **Message not delivered**: Ensure the phone number is in international format without `+` prefix (e.g., `1234567890`).
+`WhatsAppConnectorService` registers with the elizaOS message connector system. Supported capabilities: `send_message`, `read_messages`, `search_messages`, `send_reaction`, `contact_resolution`, `chat_context`, `get_user`. Target kinds: `phone`, `contact`, `user`, `group`, `room`.
 
-2. **Webhook not verified**: Check that your `WHATSAPP_WEBHOOK_VERIFY_TOKEN` matches the token configured in the Meta Developer Portal.
+Use `source: "whatsapp"` when targeting WhatsApp from an orchestrator or workflow.
+
+## Troubleshooting
 
-3. **Media upload fails**: Ensure media URLs are publicly accessible and the file format is supported by WhatsApp.
+**Messages not delivered:** Ensure phone numbers are in E.164 format (e.g. `+14155552671`). For Cloud API, bare number strings (no `+`) also work.
 
-4. **Rate limiting**: WhatsApp has rate limits on the number of messages. Implement exponential backoff for retries.
+**Webhook verification fails:** Confirm `WHATSAPP_WEBHOOK_VERIFY_TOKEN` in your env matches the token configured in the Meta Developer Portal webhook settings.
 
-### Error Codes
+**Webhook POST rejected (401):** Set `WHATSAPP_APP_SECRET` to the App Secret shown in your Meta App dashboard.
 
-| Code | Description |
-|------|-------------|
-| 130429 | Rate limit reached |
-| 131000 | Something went wrong |
-| 131030 | Invalid recipient |
-| 131051 | Message type is not supported |
+**Baileys QR not appearing:** Start a session with `POST /api/whatsapp/pair`, then poll `GET /api/whatsapp/status` (the status advances to `waiting_for_qr`). The QR itself is delivered as a `whatsapp-qr` event with a `qrDataUrl` field broadcast over the agent's WebSocket — render that data URL.
 
 ## License
 

package/auto-enable.ts

@@ -8,7 +8,7 @@ import type { PluginAutoEnableContext } from "@elizaos/core";
 
 /** Enable when a `whatsapp` connector block is present and not explicitly disabled. */
 export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
-  const c = (ctx.config?.connectors as Record<string, unknown> | undefined)
+  const c = (ctx.config.connectors as Record<string, unknown> | undefined)
     ?.whatsapp;
   if (!c || typeof c !== "object") return false;
   const config = c as Record<string, unknown>;