@standujar/plugin-whatsapp
Advanced tools
A powerful WhatsApp integration plugin for ElizaOS that enables your AI agent to communicate through WhatsApp Web using whatsapp-web.js. Features automatic session management and seamless message handling.
Features • Installation • Configuration • Usage • Advanced • Contributing
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.
# Using bun (recommended)
bun add @standujar/plugin-whatsapp
# Using npm
npm install @standujar/plugin-whatsapp
# Using yarn
yarn add @standujar/plugin-whatsapp
The plugin requires the following dependencies (automatically installed):
@elizaos/core - ElizaOS core frameworkwhatsapp-web.js - WhatsApp Web client librarypuppeteer-extra - Enhanced Puppeteer for browser automationpuppeteer-extra-plugin-stealth - Stealth plugin to avoid detection@aws-sdk/client-s3 - AWS S3 client (for optional session backup)@aws-sdk/credential-providers - AWS credential managementThe plugin can be configured using either environment variables OR character settings. Character settings take priority over environment variables.
# Required: Session name for WhatsApp authentication (must match the name used in generate-auth script)
WHATSAPP_SESSION_NAME=eliza-bot
# Optional: Enable/disable automatic replies (default: true)
WHATSAPP_AUTO_REPLY=true
# Optional: Use Puppeteer for browser automation (default: true)
WHATSAPP_USE_PUPPETEER=true
# Optional: Local auth directory path (default: .wwebjs_auth)
WHATSAPP_AUTH_PATH=.wwebjs_auth
# Optional: Comma-separated list of allowed phone numbers
WHATSAPP_ALLOWED_NUMBERS=33612345678,33698765432
# Optional: AWS S3 Configuration for session backup
WHATSAPP_S3_BUCKET=your-bucket-name
WHATSAPP_S3_REGION=eu-west-3
WHATSAPP_S3_PREFIX=sessions/
# Optional: AWS Credentials (if not using IAM roles)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=eu-west-3
Add the plugin and settings to your ElizaOS character file:
{
"name": "MyAssistant",
"plugins": ["@standujar/plugin-whatsapp"],
"settings": {
"whatsapp": {
"sessionName": "eliza-bot",
"authPath": ".wwebjs_auth",
"autoReply": true,
"usePuppeteer": true,
"allowedNumbers": [
"33612345678",
"33698765432"
]
}
}
}
All parameters can be set via environment variables (WHATSAPP_) or character settings (settings.whatsapp.):
| Parameter | Type | Default | Description |
|---|---|---|---|
sessionName | string | "eliza-bot" | Unique identifier for the WhatsApp session (must match the name used when generating the QR code) |
autoReply | boolean | true | Enable automatic message responses |
usePuppeteer | boolean | true | Use Puppeteer for browser automation |
authPath | string | ".wwebjs_auth" | Directory path for storing authentication data |
allowedNumbers | string[] | undefined | List of phone numbers allowed to interact with the bot |
s3Download | object | undefined | (Optional) S3 configuration for session backup/restore |
If you need S3 backup for production deployments, add the s3Download object:
{
"settings": {
"whatsapp": {
"s3Download": {
"bucket": "whatsapp-sessions", // Required
"region": "eu-west-3", // Optional (default: "eu-west-3")
"prefix": "sessions/" // Optional (default: "whatsapp/")
}
}
}
}
{
"plugins": ["@standujar/plugin-whatsapp"]
}
# Option A: In your .env file
WHATSAPP_SESSION_NAME=eliza-bot
# Option B: In your character settings
"settings": {
"whatsapp": {
"sessionName": "eliza-bot"
}
}
Note: The actual session folder will be
.wwebjs_auth/session-eliza-bot/(the "session-" prefix is added automatically)
Generate WhatsApp session (see Session Generation section below)
Start your ElizaOS agent:
bun start
The plugin includes helper scripts to generate WhatsApp authentication sessions. You can use either Node.js directly or Docker:
# Navigate to scripts directory
cd scripts
# Install dependencies
bun install
# Generate authentication (use the same name as in your config)
WHATSAPP_SESSION_NAME=eliza-bot bun run generate-auth
Docker provides a consistent environment with all Chrome dependencies pre-installed:
# Build the Docker image
docker build -t whatsapp-auth-generator ./scripts
# Run from your project root (where you run elizaos CLI)
# Use the same session name as in your config!
docker run -it \
-e WHATSAPP_SESSION_NAME=eliza-bot \
-v $(pwd)/.wwebjs_auth:/app/.wwebjs_auth \
whatsapp-auth-generator
# Note: Run this command from your ElizaOS project root directory
# The session will be saved in .wwebjs_auth/session-eliza-bot/ at the project root
After scanning the QR code with your WhatsApp mobile app:
.wwebjs_auth directoryThe scripts/ directory contains a utility to generate WhatsApp authentication:
generate-whatsapp-auth.js - Generates a new WhatsApp session with QR code authentication.wwebjs_auth directoryFor production deployments, you can enable S3 session backup:
{
"settings": {
"whatsapp": {
"sessionName": "production-bot",
"s3Download": {
"bucket": "my-whatsapp-sessions",
"region": "us-east-1",
"prefix": "prod/sessions/"
}
}
}
}
Restrict the bot to specific phone numbers:
{
"settings": {
"whatsapp": {
"allowedNumbers": [
"33612345678", // France
"14155552671", // US
"447911123456" // UK
]
}
}
}
For production environments, the plugin supports automatic session backup and restoration using AWS S3:
The plugin automatically detects the AWS environment:
AWS_PROFILE and AWS_DEFAULT_PROFILE environment variablesSessions are stored in S3 with the following structure:
s3://your-bucket/
└── sessions/
└── your-session-name.zip
To manually backup your session to S3:
# Zip the session directory
cd .wwebjs_auth
zip -r ../session-backup.zip session-*
cd ..
# Upload to S3
aws s3 cp session-backup.zip s3://your-bucket/sessions/your-session-name.zip
sequenceDiagram
participant U as User
participant W as WhatsApp
participant P as Plugin
participant E as ElizaOS
participant S3 as S3 (Optional)
Note over P,S3: Startup Phase
P->>S3: Check for session backup
S3-->>P: Download session (if exists)
P->>W: Initialize client
W-->>P: QR Code (if no session)
Note over U,E: Message Processing
U->>W: Send message
W->>P: Message received event
P->>P: Check allowed numbers
P->>E: Process with AI
E-->>P: Generate response
P->>W: Send response
W->>U: Deliver message
The plugin consists of several key components:
The plugin listens to the following WhatsApp events:
| Event | Description | Action |
|---|---|---|
qr | QR code generated | Display for scanning |
authenticated | Successfully authenticated | Log success |
ready | Client ready | Start message processing |
message | Message received | Queue for processing |
disconnected | Connection lost | Attempt reconnection |
The plugin uses optimized Puppeteer settings:
{
headless: true,
args: [
'--no-sandbox',
'--disable-setuid-sandbox'
],
executablePath: '/usr/bin/chromium-browser' // Or auto-detected
}
Enable debug logging to troubleshoot issues:
LOG_LEVEL=debug bun start
Common debug points:
# Clone the repository
git clone https://github.com/standujar/plugin-whatsapp.git
# Install dependencies
bun install
# Run tests
bun test
# Build the plugin
bun run build
# Run in development mode
bun run dev
bun start - Start the ElizaOS agent with the pluginbun run build - Build the TypeScript sourcebun run dev - Run in development modebun run lint - Run linting with Biomebun run format - Format code with Biomebun run clean - Clean build artifactsbun run test - Run testsThis plugin is licensed under the MIT License. See LICENSE file for details.
FAQs
WhatsApp plugin for elizaOS
We found that @standujar/plugin-whatsapp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A new npm package tests AI malware scanners with prompt injection, safety-triggering comments, context flooding, and obfuscated JavaScript.
Product
Socket now detects supply chain risks in project manifests, starting with missing lockfiles that can make dependency installs non-reproducible.
Research
/Security News
The trojanized extensions use TinyGo-compiled WebAssembly and Solana transaction memos to resolve command-and-control infrastructure.