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.

Features

• 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

Installation

TypeScript

npm install @elizaos/plugin-whatsapp

Configuration

Environment Variables

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:

import whatsappPlugin from "@elizaos/plugin-whatsapp";

export const character = {
  // ...
  plugins: [whatsappPlugin],
};

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.

To access the service at runtime (e.g. to send a message from your own code):

import type { WhatsAppConnectorService } from "@elizaos/plugin-whatsapp";

const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
await service?.sendMessage({ type: "text", to: "+14155552671", content: "hello" });

Usage

Sending Messages

The TypeScript snippets below use two variables:

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

Text Message

TypeScript:

const service = runtime.getService<WhatsAppConnectorService>("whatsapp");
await service?.sendMessage({ type: "text", to: "1234567890", content: "Hello, World!" });

Python:

Rust:

Image Message

TypeScript:

await client.sendImage('1234567890', 'https://example.com/image.jpg', 'Caption');

Python:

Rust:

Interactive Button Message

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'
);

Python:

Rust:

Sending Reactions

TypeScript:

await client.sendReaction({
    to: '1234567890',
    messageId: 'wamid.xxx',
    emoji: '👍',
});

// Remove reaction
await client.removeReaction('1234567890', 'wamid.xxx');

Python:

Rust:

Handling Webhooks

TypeScript:

import express from 'express';

const app = express();

const service = runtime.getService<WhatsAppConnectorService>("whatsapp");

// 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);
    }
});

// Message handling endpoint
app.post('/webhook', express.json(), async (req, res) => {
    await service?.handleWebhook(req.body);
    res.sendStatus(200);
});

Python:

Rust:

Event Handling

TypeScript (using event emitter pattern):

// Events are emitted by the webhook handler
webhookHandler.onMessage((message) => {
    console.log('Message received:', message);
});

webhookHandler.onStatus((status) => {
    console.log('Status update:', status);
});

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.

Event Types

Common Reactions

The plugin provides constants for common reaction emojis:

API Reference

WhatsAppClient / WhatsAppService

Troubleshooting

Common Issues

1. Message not delivered: Ensure the phone number is in international format without + prefix (e.g., 1234567890).

2. Webhook not verified: Check that your WHATSAPP_WEBHOOK_VERIFY_TOKEN matches the token configured in the Meta Developer Portal.

3. Media upload fails: Ensure media URLs are publicly accessible and the file format is supported by WhatsApp.

4. Rate limiting: WhatsApp has rate limits on the number of messages. Implement exponential backoff for retries.

Error Codes

License

MIT