Connect WhatsApp

Link your Moltbot AI assistant to WhatsApp for intelligent automated replies

Easy ⏱️ 3 min

Overview

This guide will help you connect Moltbot to WhatsApp, enabling your AI assistant to:

  • Automatically reply to messages from specific contacts
  • Process voice messages and respond
  • Send images, files and other media

⚠️ Note: Moltbot uses the WhatsApp Web protocol, so your phone needs to stay connected to the internet.

Prerequisites

  • Moltbot installed on your machine
  • An active WhatsApp account
  • WhatsApp app installed on your phone

Step 1: Start the WhatsApp Connection Wizard

Run this command in Terminal:

moltbot channels add whatsapp

Or use the setup wizard:

moltbot onboard

Then select Add messaging channel → WhatsApp.

Step 2: Scan the QR Code

After running the command, a QR code will appear in your terminal.

  1. Open WhatsApp on your phone
  2. Tap the ⋮ menu (three dots) in the top right
  3. Select Linked Devices
  4. Tap Link a Device
  5. Scan the QR code displayed in your terminal

Once successful, you’ll see:

✓ WhatsApp connected!
✓ Logged in as: +1 555****1234

Step 3: Configure Allow List (Optional)

For security, you may want to restrict which contacts can interact with the AI:

moltbot config set whatsapp.allowList "+15551234567,+15559876543"

Or use pairing mode, where users must send a secret code before they can chat:

moltbot config set pairing.enabled true
moltbot config set pairing.code "my-secret-code"

Step 4: Test the Connection

  1. Start the gateway: moltbot gateway
  2. Send a message to your WhatsApp from another phone
  3. Watch the terminal to confirm the message is received and processed

If everything is working, the AI will automatically reply!

Advanced Configuration

Group Chat Support

Enable AI replies in group chats:

moltbot config set whatsapp.groups.enabled true

In groups, the AI will only respond to messages that @mention it.

Custom Trigger Word

Set a specific prefix to trigger AI responses:

moltbot config set whatsapp.trigger "@ai"

With this setting, only messages starting with @ai will get a response.

Troubleshooting

QR Code Won’t Scan

  • Make sure the terminal window is large enough to display the full QR code
  • Try reducing the terminal font size
  • Or use moltbot channels add whatsapp --qr-size small

Connection Keeps Dropping

WhatsApp Web requires your phone to maintain an internet connection. If the connection drops frequently:

  • Keep your phone connected to Wi-Fi
  • Disable battery saver mode
  • Periodically open the WhatsApp app to refresh the connection

Messages Not Sending

Check that your API key is configured correctly:

moltbot config get provider
moltbot status

Next Steps