How to Connect Moltbot to WhatsApp

WhatsApp integration is one of the most requested features for Moltbot. Being able to message your AI assistant through the world's most popular messaging app opens up incredible possibilities for automation and productivity. This guide covers everything you need to know to get it working.

Understanding Your Options

There are two main approaches to connecting Moltbot to WhatsApp, each with different trade-offs:

Option 1: WhatsApp Web Bridge (Recommended for Personal Use)

This method uses automation to connect through WhatsApp Web. It's free, works with your personal WhatsApp account, and doesn't require Meta developer approval.

• Pros: Free, uses your existing number, quick to set up
• Cons: Against WhatsApp ToS, can get your account banned, less reliable
• Best for: Personal use, experimentation, low-volume messaging

Option 2: WhatsApp Business API (Recommended for Business)

The official API for businesses. Requires Meta approval and has usage costs, but is fully sanctioned and reliable.

• Pros: Official, reliable, won't get banned, better features
• Cons: Costs money, requires business verification, complex setup
• Best for: Businesses, production use, high-volume messaging

We'll cover both methods in this guide. If you're just experimenting or want personal use, start with Option 1. If this is for a business, skip to Option 2.

Option 1: WhatsApp Web Bridge Setup

Step 1: Install the Bridge Package

Moltbot uses whatsapp-web.js for the bridge connection. SSH into your server and install:

cd ~/moltbot
npm install whatsapp-web.js

Step 2: Enable the Integration

In your .env file, add:

WHATSAPP_ENABLED=true
WHATSAPP_SESSION_PATH=./whatsapp-session

Step 3: Configure Moltbot

Edit your skills/whatsapp/config.json:

{
  "enabled": true,
  "allowedNumbers": ["+1234567890"],
  "adminNumbers": ["+1234567890"],
  "responseDelay": 1000,
  "typingIndicator": true
}

Step 4: First-Time Authentication

Start Moltbot in interactive mode for the first run:

npm run start:interactive

A QR code will appear in your terminal. Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device). Once linked, the session is saved and you can restart in normal mode.

Step 5: Testing

Send a message from an allowed number to your WhatsApp. You should see it processed in the Moltbot logs and receive a response.

Option 2: WhatsApp Business API Setup

Prerequisites

• A Meta Business account
• A Facebook Business page
• A phone number that isn't already on WhatsApp
• Business verification (can be skipped for testing)

Step 1: Create a Meta App

1. Go to developers.facebook.com
2. Create a new app, select "Business" type
3. Add the WhatsApp product
4. Complete the quick start to get a test phone number

Step 2: Get Your Credentials

In the Meta developer dashboard, you'll need:

• Phone Number ID
• WhatsApp Business Account ID
• Temporary or Permanent Access Token

Step 3: Configure Moltbot

Add to your .env file:

WHATSAPP_API_ENABLED=true
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_BUSINESS_ACCOUNT_ID=your_business_account_id
WHATSAPP_ACCESS_TOKEN=your_access_token

Step 4: Set Up Webhooks

WhatsApp Business API uses webhooks for incoming messages. You'll need your server exposed to the internet with a valid SSL certificate.

In the Meta developer dashboard, configure the webhook URL:

https://your-domain.com/api/whatsapp/webhook

Subscribe to the "messages" webhook field. The verify token is in your .env file as WHATSAPP_WEBHOOK_VERIFY_TOKEN.

Step 5: Testing

Use the test messaging feature in the Meta dashboard to send a message to your test number. Check Moltbot logs to verify it's being received and processed.

Best Practices for WhatsApp Integration

Security Considerations

• Whitelist numbers: Only allow specific numbers to interact with your bot
• Rate limiting: Prevent abuse with message limits per user
• Content filtering: Be careful what your AI can access via WhatsApp
• Audit logging: Keep records of all interactions

User Experience Tips

• Typing indicators: Show typing to make it feel more natural
• Response delay: Add small delays to seem more human-like
• Message chunking: Break long responses into multiple messages
• Error handling: Graceful fallbacks when AI fails

Common Issues and Solutions

"Session expired" errors

For Web Bridge: The WhatsApp session can expire if your phone disconnects or the server restarts. Re-scan the QR code to fix.

Messages not being received

For Business API: Check that webhooks are properly configured and your server is accessible. Verify the webhook URL in Meta dashboard shows successful verification.

Slow responses

This is usually the AI taking time to respond, not WhatsApp. Check your AI provider's status and consider upgrading your hosting if it's CPU-bound.

Getting banned (Web Bridge)

If you're sending too many messages too quickly, WhatsApp may flag your account. Add delays between messages and keep volume low for personal accounts.

Advanced: Multi-Number Setup

For business use, you might want different AI personalities for different WhatsApp numbers. Moltbot supports this through its multi-tenant configuration:

{
  "tenants": [
    {
      "phoneId": "phone_1",
      "personality": "professional",
      "skills": ["calendar", "email"]
    },
    {
      "phoneId": "phone_2",
      "personality": "casual",
      "skills": ["general", "fun"]
    }
  ]
}

Summary

Connecting Moltbot to WhatsApp unlocks powerful capabilities for personal productivity and business automation. The Web Bridge is great for personal experimentation, while the Business API is the right choice for production use.

Remember to implement proper security measures - WhatsApp integration means your AI is accessible from anywhere, which increases your attack surface. Whitelist numbers, enable audit logging, and follow the security best practices we've covered.