WhatsApp Connector

Connect your agent to WhatsApp for private chats and group conversations via personal or business accounts using the @elizaos/plugin-whatsapp package.

Prerequisites

For Baileys (personal): A phone with WhatsApp installed (for QR code scanning)
For Cloud API (business): A WhatsApp Business Account and access tokens from the Meta Developer Dashboard

Configuration

Name	Required	Description
`WHATSAPP_AUTH_METHOD`	No	Authentication method: `cloudapi` or `baileys`
`WHATSAPP_ACCESS_TOKEN`	No	WhatsApp Business API access token (required for `cloudapi` auth)
`WHATSAPP_PHONE_NUMBER_ID`	No	Phone number ID from Meta Developer Dashboard (required for `cloudapi` auth)
`WHATSAPP_AUTH_DIR`	No	Directory for Baileys session files (required for `baileys` auth)
`WHATSAPP_PRINT_QR`	No	Print QR code in terminal when using Baileys auth
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	No	Webhook verification token
`WHATSAPP_BUSINESS_ACCOUNT_ID`	No	WhatsApp Business Account ID
`WHATSAPP_API_VERSION`	No	API version string
`WHATSAPP_DM_POLICY`	No	DM policy (e.g., `allow`, `deny`, `allowlist`)
`WHATSAPP_GROUP_POLICY`	No	Group message policy

The connector auto-enables when authDir, authState, sessionPath, or accounts with at least one account having authDir is present, and enabled is not explicitly false.

Minimal Configuration

In ~/.eliza/eliza.json (Baileys / QR code):

json

{
  "connectors": {
    "whatsapp": {
      "accounts": {
        "default": {
          "enabled": true,
          "authDir": "./auth/whatsapp"
        }
      }
    }
  }
}

Or with a top-level authDir (single account shorthand):

json

{
  "connectors": {
    "whatsapp": {
      "authDir": "./whatsapp-auth"
    }
  }
}

Disabling

To explicitly disable the connector even when auth config is present:

json

{
  "connectors": {
    "whatsapp": {
      "authDir": "./whatsapp-auth",
      "enabled": false
    }
  }
}

Setup

Baileys (personal account)

Set authDir in your connector config (e.g., "./auth/whatsapp").
Start Eliza -- a QR code will be printed to the terminal.
Scan the QR code with your phone (WhatsApp > Settings > Linked Devices > Link a Device).
The session persists automatically across restarts.

Cloud API (business account)

Set up a WhatsApp Business Account in the Meta Developer Dashboard.
Obtain an access token and phone number ID.
Set WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, and WHATSAPP_AUTH_METHOD=cloudapi.
Configure a webhook URL pointing to your Eliza instance.
Start your agent.

Authentication Methods

Baileys (QR Code)

Baileys connects via the WhatsApp Web multi-device protocol. No API keys or business accounts are needed. On first start, a QR code is printed to the terminal. Scan it with your phone (WhatsApp > Settings > Linked Devices > Link a Device) to authenticate.

Pros: No API costs, works with personal accounts, full feature access. Cons: Requires a phone with WhatsApp linked, session can expire if phone disconnects.

Cloud API (Business)

The WhatsApp Business Cloud API is Meta's official API. Requires a WhatsApp Business Account and access tokens from the Meta Developer Dashboard.

Pros: Official API, reliable uptime, webhook-based. Cons: Requires business account, per-message costs may apply, approval process.

Features

Private and group chat messaging
Two auth methods: Baileys (QR code, personal) and Cloud API (business)
Read receipts and acknowledgment reactions
DM and group access policies
Media attachments up to 50MB
Multi-account support
Self-chat mode for testing
Session persistence across restarts

Full Configuration Reference

All fields are defined under connectors.whatsapp in eliza.json.

Core Fields

Field	Type	Default	Description
`accounts`	object	--	Named account configurations (see Multi-Account below)
`authDir`	string	--	Directory for Baileys session files (single-account shorthand)
`enabled`	boolean	--	Explicitly enable/disable
`dmPolicy`	`"pairing"` \| `"allowlist"` \| `"open"` \| `"disabled"`	`"pairing"`	DM acceptance policy. `"open"` requires `allowFrom` to include `"*"`
`allowFrom`	string[]	--	Allowlist of phone numbers (required when `dmPolicy: "open"`)
`groupPolicy`	`"open"` \| `"disabled"` \| `"allowlist"`	`"allowlist"`	Group message policy
`groupAllowFrom`	string[]	--	Allowlist of group JIDs
`historyLimit`	number	--	Max messages to load from conversation history
`dmHistoryLimit`	number	--	Max messages for DM history
`textChunkLimit`	number	--	Max characters per outgoing message chunk
`chunkMode`	`"length"` \| `"newline"`	--	Long message splitting strategy
`mediaMaxMb`	number	`50`	Max media attachment size in MB
`sendReadReceipts`	boolean	--	Send read receipts for incoming messages
`selfChatMode`	boolean	--	Respond to your own messages (for testing; avoid in production)
`messagePrefix`	string	--	Text prefix added to all outgoing messages
`debounceMs`	number	`0`	Delay in ms before responding, to allow message batching
`blockStreaming`	boolean	--	Disable streaming responses
`groups`	object	--	Per-group configuration overrides

Acknowledgment Reactions

Configure emoji reactions sent as message acknowledgments:

json

{
  "connectors": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "eyes",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

Field	Type	Default	Description
`ackReaction.emoji`	string	--	Reaction emoji to send as acknowledgment
`ackReaction.direct`	boolean	`true`	Send ack reactions in DMs
`ackReaction.group`	string	`"mentions"`	Group ack behavior: `"always"`, `"mentions"`, or `"never"`

Multi-Account Support

The accounts field allows running multiple WhatsApp sessions from a single agent. Each account gets its own Baileys auth directory and QR code pairing flow.

json

{
  "connectors": {
    "whatsapp": {
      "accounts": {
        "account-1": {
          "enabled": true,
          "authDir": "./auth/whatsapp-1"
        },
        "account-2": {
          "enabled": true,
          "authDir": "./auth/whatsapp-2"
        }
      }
    }
  }
}

Each account under accounts.<name> supports all top-level fields plus:

Field	Type	Description
`enabled`	boolean	Enable or disable this account
`authDir`	string	Directory for Baileys session files (required per account)
`name`	string	Display name for this account

Self-Chat Mode

When selfChatMode is true, the agent responds to messages you send to yourself (the "Message Yourself" chat). This is useful for testing without involving other contacts. Avoid enabling in production.

json

{
  "connectors": {
    "whatsapp": {
      "selfChatMode": true
    }
  }
}

Session Persistence

Baileys saves its session state to the directory specified by authDir. This includes:

Encryption credentials
Device registration info
Authentication keys

The session persists across restarts. A new QR code is only generated when:

The session files in authDir are deleted or corrupted
Your phone revokes the linked device (Settings > Linked Devices > remove)
The session expires due to prolonged disconnection

Security considerations:

Never commit the auth directory to version control (auth/ should be in .gitignore)
Back up the auth directory to avoid re-scanning on a new machine
The auth directory contents grant full access to the linked WhatsApp session

Troubleshooting

Plugin Not Loading

Verify that at least one of the auto-enable triggers is present in your config:

authDir at the top level, or
At least one account under accounts with authDir set and enabled: true

QR Code Expires

QR codes have a short TTL (typically around 20 seconds). The connector automatically generates a new QR code when the previous one expires. Make sure your phone has internet access when scanning.

Session Expired

If reconnection fails with a session error:

Delete the contents of your authDir directory
Restart Eliza
Scan the new QR code

`dmPolicy: "open"` Validation Error

When setting dmPolicy to "open", you must also set allowFrom: ["*"]. This is a safety requirement enforced by the config validator:

json

{
  "dmPolicy": "open",
  "allowFrom": ["*"]
}

Rate Limits

WhatsApp has undocumented rate limits. If the agent sends messages too rapidly, the connection may be throttled or temporarily banned. Use debounceMs to add delays:

json

{
  "debounceMs": 1000
}

WhatsApp Connector

WhatsApp Connector

Prerequisites

Configuration

Minimal Configuration

Disabling

Setup

Baileys (personal account)

Cloud API (business account)

Authentication Methods

Baileys (QR Code)

Cloud API (Business)

Features

Full Configuration Reference

Core Fields

Acknowledgment Reactions

Multi-Account Support

Self-Chat Mode

Session Persistence

Troubleshooting

Plugin Not Loading

QR Code Expires

Session Expired

dmPolicy: "open" Validation Error

Rate Limits

Related

`dmPolicy: "open"` Validation Error