Skip to main content

WhatsApp Integration

DotAgents includes a WhatsApp MCP server that lets your agents send and receive WhatsApp messages.

Overview​

The WhatsApp integration is packaged as an MCP server in packages/mcp-whatsapp. It uses the Baileys WhatsApp Web library, persists auth credentials locally, and exposes WhatsApp operations as MCP tools. Once configured, your agents can:

  • Send messages to WhatsApp contacts
  • Receive incoming messages
  • Read recent chat history
  • Check pending messages
  • Participate in WhatsApp conversations through the agent interface or auto-reply flow

Setup​

1. Configure the MCP Server​

Add the WhatsApp MCP server to your configuration:

{
  "mcpServers": {
    "whatsapp": {
      "transport": "stdio",
      "command": "node",
      "args": ["packages/mcp-whatsapp/dist/index.js"],
      "env": {
        "WHATSAPP_AUTH_DIR": "~/.dotagents/whatsapp-auth",
        "WHATSAPP_ALLOW_FROM": "14155551234",
        "WHATSAPP_LOG_MESSAGES": "false"
      }
    }
  }
}

2. WhatsApp Settings​

Configure WhatsApp-specific settings in Settings > WhatsApp:

  • Connection status
  • Session management
  • Message routing preferences

3. Enable for Your Agent​

Ensure your agent's tool configuration includes the WhatsApp server:

{
  "toolConfig": {
    "enabledServers": ["whatsapp"]
  }
}

Available Tools​

Once connected, the WhatsApp MCP server exposes these tools:

ToolDescription
whatsapp_send_messageSend a text message to a phone number or chat.
whatsapp_get_messagesRetrieve recent messages from a chat.
whatsapp_list_chatsList available chats with recent activity.
whatsapp_get_pending_messagesReturn messages that arrived since the last poll.
whatsapp_get_statusCheck connection and auth status.
whatsapp_connectConnect to WhatsApp and generate a QR code if needed.
whatsapp_disconnectDisconnect while keeping stored credentials.
whatsapp_logoutLog out and clear stored credentials.

Environment Variables​

VariablePurposeDefault
WHATSAPP_AUTH_DIRDirectory for Baileys auth credentials~/.dotagents/whatsapp-auth
WHATSAPP_ALLOW_FROMComma-separated phone numbers allowed to message the agentEmpty means all senders
WHATSAPP_OPERATOR_ALLOW_FROMComma-separated phone numbers allowed to run /ops commandsEmpty means operator commands disabled
WHATSAPP_AUTO_REPLYAutomatically call DotAgents for allowed incoming messagesfalse
WHATSAPP_CALLBACK_URLDotAgents chat completions URL for auto-reply—
WHATSAPP_CALLBACK_API_KEYBearer token for the callback URL—
WHATSAPP_LOG_MESSAGESLog message content for diagnosticsfalse

Usage​

Ask your agent to interact with WhatsApp:

"Send a message to John saying I'll be 10 minutes late"

"Check my latest WhatsApp messages"

"Reply to the team group chat with the meeting summary"

The agent will use the WhatsApp MCP tools to carry out the action.

Auto-Reply​

Auto-reply sends allowed incoming WhatsApp messages to the DotAgents remote server and posts the agent response back to WhatsApp.

  1. Enable Settings > Remote Server in the desktop app.
  2. Copy the remote server API key.
  3. Configure the WhatsApp MCP server with:
{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["packages/mcp-whatsapp/dist/index.js"],
      "env": {
        "WHATSAPP_AUTO_REPLY": "true",
        "WHATSAPP_CALLBACK_URL": "http://127.0.0.1:3210/v1/chat/completions",
        "WHATSAPP_CALLBACK_API_KEY": "your-remote-server-api-key",
        "WHATSAPP_ALLOW_FROM": "14155551234"
      }
    }
  }
}

Keep WHATSAPP_ALLOW_FROM narrow for auto-reply. Treat WHATSAPP_CALLBACK_API_KEY like a secret.

Operator Commands​

WhatsApp supports the same /ops operator command family as Discord when WHATSAPP_OPERATOR_ALLOW_FROM is configured. Operator commands can inspect status, health, logs, audit events, tunnels, integrations, updater state, MCP status, and can restart services or run an agent.

Operator access is separate from normal WhatsApp messaging access. A number in WHATSAPP_ALLOW_FROM can chat with the agent, but it cannot run /ops unless it is also in WHATSAPP_OPERATOR_ALLOW_FROM.

Security Notes​

  • Use WHATSAPP_ALLOW_FROM before enabling auto-reply.
  • Use WHATSAPP_OPERATOR_ALLOW_FROM only for trusted phone numbers.
  • Keep WHATSAPP_LOG_MESSAGES=false unless you need message-level diagnostics.
  • Baileys is an unofficial WhatsApp Web library; use it with that account-risk tradeoff in mind.

Next Steps​