@standujar/plugin-whatsapp

@standujar/plugin-whatsapp

WhatsApp plugin for ElizaOS that enables WhatsApp messaging capabilities.

Features

• WhatsApp Web integration using QR code authentication (via whatsapp-web.js)
• S3-based session storage for multi-instance support
• Send and receive messages
• Group chat support
• Media handling (images, audio, documents)
• Message reactions and replies
• Contact management
• Status updates

Note: This plugin uses whatsapp-web.js which automates WhatsApp Web. It does not use the official WhatsApp Business API. For business-critical applications, consider using official WhatsApp Business API solutions.

Installation

npm install @standujar/plugin-whatsapp

Configuration

Environment Variables

# Basic configuration
WHATSAPP_SESSION_NAME=eliza-whatsapp-session
WHATSAPP_AUTO_REPLY=true
WHATSAPP_USE_PUPPETEER=true

# S3 Session Storage (Required for production)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1
WHATSAPP_S3_BUCKET=whatsapp-sessions
WHATSAPP_S3_PREFIX=sessions/

# Optional: Future WhatsApp Business API support
# WHATSAPP_PHONE_NUMBER=[phone]
# WHATSAPP_API_TOKEN=your-api-token
# WHATSAPP_WEBHOOK_URL=https://your-webhook-url.com

# Optional: Security
WHATSAPP_ALLOWED_NUMBERS=[phone],+0987654321

Authentication Flow

• Frontend QR Generation: A frontend application generates the WhatsApp QR code
• S3 Storage: The session data is stored in S3 after successful authentication
• Plugin Session Retrieval: The plugin retrieves the session from S3 for subsequent connections
• Automatic Reconnection: The plugin automatically reconnects using the stored session

Usage

Adding to Your ElizaOS Agent

import { whatsappPlugin } from '@standujar/plugin-whatsapp';

export default {
  name: "MyAgent",
  plugins: [whatsappPlugin],
  // ... other configuration
};

Basic Example

import { ElizaOS } from '@elizaos/core';
import { whatsappPlugin } from '@standujar/plugin-whatsapp';

const agent = new ElizaOS({
  character: {
    name: "WhatsAppBot",
    plugins: [whatsappPlugin]
  }
});

agent.start();

Actions

sendWhatsAppMessage

Send a message to a WhatsApp contact or group.

sendWhatsAppMedia

Send media files (images, videos, documents) via WhatsApp.

getWhatsAppContacts

Retrieve the list of WhatsApp contacts.

createWhatsAppGroup

Create a new WhatsApp group.

Providers

whatsappMessageProvider

Provides WhatsApp message history and context.

whatsappContactProvider

Provides WhatsApp contact information.

Services

WhatsAppService

Main service handling WhatsApp Web connection and message routing.

Development

# Install dependencies
bun install

# Build the plugin
bun run build

# Run tests
bun test

# Development mode
bun run dev

License

MIT